---
title: V8 API Remote Execution
description: "# 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…"
url: "https://legacy.rtila.com/docs/v8-api-remote-execution/"
updated: "2025-11-30"
category: "API & Cloud"
---

# 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](/docs/v8-api-overview/).

## Endpoint Summary

| Method | `POST` |
| --- | --- |
| Path | `/api/remote` |
| Base URL (Local) | `http://127.0.0.1:8880` |
| Base URL (Remote/Public) | `https://YOUR_PUBLIC_RTILA_HOST` |

## Request

### Headers

| Header | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | `Bearer YOUR_SYSTEM_AUTH_TOKEN` (JWT from RTILA Studio). |
| `Content-Type` | `string` | Yes | `application/json` |

### Body (Basic Usage)

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

```json
{
  "api_key": "fad41960-7831-4f36-b9e2-d5ff87ff8ef8",
  "variables": {
    "query": "web scraping"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | `string` | Yes | Project remote key (`remote.api_key`) that identifies the project to run. |
| `variables` | `object` | No | 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](#advanced-settings).

## Basic cURL Example (Local)

```bash
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)

```bash
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.

```json
{
  "message": "Project execution successfully queued.",
  "queueId": "ilh2f81bq46wedu"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Confirmation message. |
| `queueId` | `string` | Unique ID for this run. Use it later as `sessionId` in [`GET /api/results`](/docs/v8-api-results-endpoint/). |

## Error Responses

| Status | Meaning | Typical Cause |
| --- | --- | --- |
| `400` | Bad Request | Missing `api_key`, invalid JSON body, wrong types. |
| `401` | Unauthorized | Missing or invalid Bearer token. |
| `403` | Forbidden | Token is valid but not allowed to run this project. |
| `500` | Internal Server Error | Unexpected 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.

```json
{
  "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)

```json
"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:

```json
"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)

```json
"humanoid": {
  "enabled": true
}
```

Enable human-like interaction simulation per call.

#### `captcha_resolver` (object)

```json
"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`

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

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

### Full Advanced Example

```bash
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"
    }
  }'
```

Next: learn how to retrieve execution results with [V8 API Results Endpoint (`/api/results`)](/docs/v8-api-results-endpoint/).