View Categories

V8 API Remote Execution

V8 API Remote Execution (/api/remote) #

The Remote Execution endpoint allows you to start an RTILA project programmatically, pass variables at runtime, and optionally override project settings on a per-request basis.

For a high-level picture of how this fits into the full workflow, see V8 API Overview.

Endpoint Summary #

MethodPOST
Path/api/remote
Base URL (Local)http://127.0.0.1:8880
Base URL (Remote/Public)https://YOUR_PUBLIC_RTILA_HOST

Request #

Headers #

HeaderTypeRequiredDescription
AuthorizationstringYesBearer YOUR_SYSTEM_AUTH_TOKEN (JWT from RTILA Studio).
Content-TypestringYesapplication/json

Body (Basic Usage) #

For most use cases you only need to send the project api_key and an optional variables object.

{
  "api_key": "fad41960-7831-4f36-b9e2-d5ff87ff8ef8",
  "variables": {
    "query": "web scraping"
  }
}
FieldTypeRequiredDescription
api_keystringYes Project remote key (remote.api_key) that identifies the project to run.
variablesobjectNo Arbitrary key/value pairs available to the project as runtime variables (e.g. search terms, IDs).

Advanced users can also send a settings object to override project configuration at runtime. This is covered in Advanced Settings Overrides.

Basic cURL Example (Local) #

curl -X POST "http://127.0.0.1:8880/api/remote" \
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "fad41960-7831-4f36-b9e2-d5ff87ff8ef8",
    "variables": {
      "query": "web scraping"
    }
  }'

Basic cURL Example (Remote/Public) #

curl -X POST "https://YOUR_PUBLIC_RTILA_HOST/api/remote" \
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_PROJECT_API_KEY",
    "variables": {
      "query": "web scraping"
    }
  }'

Response #

On success, RTILA queues the execution and immediately returns a JSON response containing a queueId. The actual scraping continues asynchronously.

{
  "message": "Project execution successfully queued.",
  "queueId": "ilh2f81bq46wedu"
}
FieldTypeDescription
messagestringConfirmation message.
queueIdstring Unique ID for this run. Use it later as sessionId in GET /api/results.

Error Responses #

StatusMeaningTypical Cause
400Bad RequestMissing api_key, invalid JSON body, wrong types.
401UnauthorizedMissing or invalid Bearer token.
403ForbiddenToken is valid but not allowed to run this project.
500Internal Server ErrorUnexpected error while queuing the execution.

Advanced Settings Overrides (settings) #

You can override most project settings at runtime via a settings object in the request body. These overrides are merged into the stored configuration, and values in the payload take precedence.

{
  "api_key": "YOUR_PROJECT_API_KEY",
  "settings": {
    /* per-call overrides go here */
  },
  "variables": {
    /* optional variables */
  }
}

Execution Control #

  • headless (boolean) – true for Faster background execution, false for a visible browser (debugging).
  • max_concurrent_workers (number) – controls how many parallel workers are used.
  • navigation_timeout (number, ms) – page load timeout; adjust for slow or fast targets.

Anonymity & Anti-Block Controls #

proxy (object) #

"proxy": {
  "enabled": true,
  "addresses": [
    "http://user:pass@host1:port",
    "http://user:pass@host2:port"
  ]
}

Use this to inject a per-run proxy list managed by your backend.

user_agent (string) #

Override the browser User-Agent for a specific run:

"settings": {
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
}

Example user agents:

  • Windows 10/11 Chrome:
    Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36
  • macOS Safari:
    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.1.15
  • Android Mobile Chrome:
    Mozilla/5.0 (Linux; Android 13; SM-S908B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36

humanoid (object) #

"humanoid": {
  "enabled": true
}

Enable human-like interaction simulation per call.

captcha_resolver (object) #

"captcha_resolver": {
  "enable": true,
  "api_key": "DIFFERENT_2CAPTCHA_KEY"
}

Enable CAPTCHA solving or override the CAPTCHA API key for this run.

Performance Tuning: block_resources #

"block_resources": {
  "enabled": true,
  "types": ["image", "stylesheet", "font"]
}

Block heavy resources (images, fonts, stylesheets) to speed up data-only scraping.

Full Advanced Example #

curl -X POST "https://YOUR_PUBLIC_RTILA_HOST/api/remote" \
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_PROJECT_API_KEY",
    "settings": {
      "urls": [
        "https://books.toscrape.com/catalogue/sapiens-a-brief-history-of-humankind_996/index.html"
      ],
      "headless": true,
      "max_concurrent_workers": 3,
      "proxy": {
        "enabled": true,
        "addresses": [
          "http://your_proxy_user:your_proxy_pass@proxy.server.com:8080"
        ]
      },
      "block_resources": {
        "enabled": true,
        "types": ["image", "font"]
      },
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
    },
    "variables": {
      "source_system": "external_api_call"
    }
  }'