# Start a run

> operationId: `startRun`


## Request

This endpoint starts a template run. It accepts only a complete saved template. Drafts, single nodes, and arbitrary modes are not supported. All parameters use {kind:"json",value:…}. Pass private parameters as plain-text strings, and pass file parameters as absolute local paths (a string for a single file, an array of strings for multiple files). See [ParameterValues](/browser-rpa/api/data-types#parametervalues). Unknown parameters are rejected. External runs have the same capabilities as runs in the client, with no restrictions on node or parameter types. Requests with the same key are registered at most once. This does not guarantee exactly-once actions on third-party websites.

- **Prerequisites**: The user has authorized the run. You have queried the actual environment and passed validation with purpose=run, and you use the exact saved template version.
- **Authentication**: Same as the rest of the Local API; see [Authentication](/api-reference/getting-started/authentication). Resources belong to the current account/team data scope.
- **Side effects**: This call registers one run with a frozen snapshot of the template and its dependencies. The run can then start a browser and cause side effects on websites.
- **Completion signal**: 202 with Location and runId only means that registration succeeded. To learn the execution result, read the run details until the run reaches a terminal state.
- **Retries**: To recover the same intent, reuse the original key, the original body (if any), and the original If-Match (when this endpoint requires it). On an HTTP timeout, first [check the request receipt](/browser-rpa/api/get-request-receipt). Do not generate a new key.


### Endpoint

```http
POST /api/rpa/browser/v1/runs
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/runs`. Use the port configured in the client.

### Headers

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `Authorization` | string | When Local API authentication is enabled | See [Authentication](/api-reference/getting-started/authentication). |
| `Idempotency-Key` | string | No | Recommended. Generate a UUID for each new write intent and keep it when you retry after a disconnect; the same key never runs twice. Without it there is no duplicate protection, so a retry after a timeout can run the write again. When present, it must be a UUID. Format "uuid" |
| `X-RPA-Catalog-Revision` | string | Yes | The catalogRevision returned by GET capabilities. |


Content type: `Content-Type: application/json` (required).

### Path parameters

None.

### Query parameters

None.

### Request body

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `templateId` | string | Yes | Target template ID (the cloud ID of the template in Custom Templates in the client, a numeric string). Min length 1; max length 128. |
| `version` | integer | Yes | Current editable template version. Read it from an actual response. Minimum 1. |
| `environmentId` | string | Yes | ID of an actual environment. Get it from an environment query. Min length 1; max length 128. |
| `parameters` | [ParameterValues](/browser-rpa/api/data-types#parametervalues) | Yes | Map from parameter names to {kind:json,value:JSON} (plain text for private parameters, absolute local paths for file parameters; see ParameterValues). Use {} when there are no parameters. |


Full model: [StartRun](/browser-rpa/api/data-types#startrun).

### Request example

This is a documentation example; it was not sent to a live client. Set `RPA_BASE_URL` as described in [API conventions](/browser-rpa/api/common). Resource variables, the catalog revision, and ETags come from actual responses.

Save the complete JSON below as `start-run.request.json`. Replace every value whose identifier contains `example` with a value from an actual response. The node IDs in the creation sample are workflow-local IDs and can stay as they are.

```json
{
  "templateId": "template_example",
  "version": 1,
  "environmentId": "environment_example",
  "parameters": {
    "targetUrl": {
      "kind": "json",
      "value": "https://example.com"
    }
  }
}
```

```bash
curl -i -X POST "${RPA_BASE_URL}/runs" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: ${RPA_REQUEST_KEY}" \
  -H "X-RPA-Catalog-Revision: ${RPA_CATALOG_REVISION}" \
  --data-binary @start-run.request.json
```

## Response

### 202

202 with Location and runId only means that registration succeeded. To learn the execution result, read the run details until the run reaches a terminal state.

| Header | Description |
|  --- | --- |
| `Location` | Details URL of the registered run. |


Body: `application/json`. The top-level `data` uses the model below. For `meta`, see [Metadata](/browser-rpa/api/data-types#metadata).

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `status` | [RunStatus](/browser-rpa/api/data-types#runstatus) | Yes | Current status, checked against the model's enum. |
| `template` | object | Yes | Complete body of the candidate template, or a summary of the template frozen for the run. Read it according to the model that contains it. |
| `environment` | object | Yes | Summary of the target environment frozen for the run. |
| `createdAt` | integer | Yes | Creation time, Unix milliseconds. Minimum 0. |
| `startedAt` | integer or null | Yes | Start time. It is null if the run has not started yet (always present in node records). |
| `endedAt` | integer or null | Yes | End time. It is null if the run has not ended yet. |
| `startAfter` | integer or null | Yes | Earliest start time when the template task is set to start with a delay, Unix milliseconds. Before that time, the run stays queued and does not occupy the environment. It is null when there is no delay or for a debug run. |
| `hasNodeErrors` | boolean | Yes | Whether any node error occurred. Do not look only at the overall status and ignore this field. |
| `isolation` | object or null | Yes | Environment isolation state, or null. When it is quarantined, the environment cannot be reused. |


**`template` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `template.id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `template.title` | string | Yes | Display name. On template writes, 1–100 characters after trimming. |
| `template.version` | integer | Yes | Current editable template version. Read it from an actual response. Minimum 1. |
| `template.revisionId` | string | Yes | Immutable revision ID. Min length 1; max length 128. |


**`environment` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `environment.id` | string | Yes | Unique ID of the resource or node. Take it from a previous response; don't guess it. Min length 1; max length 128. |
| `environment.name` | string | Yes | Public name. |


**`isolation` fields**

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `isolation.state` | `quarantined` / `released` | Yes | Environment isolation state: quarantined or released. |
| `isolation.reason` | string | Yes | Reason for unavailability, isolation, or the runtime check. |
| `isolation.since` | integer | Yes | Time the isolation started, Unix milliseconds. Minimum 0. |
| `isolation.releasedAt` | integer or null | Yes | Release time. It is null if the environment has not been released yet. |


### Response example

All IDs, timestamps, hashes, and run results are sample data. They don't indicate that the sample was executed.

```json
{
  "data": {
    "id": "run_example",
    "status": "queued",
    "template": {
      "id": "template_example",
      "title": "Read the page URL",
      "version": 1,
      "revisionId": "revision_example_1"
    },
    "environment": {
      "id": "environment_example",
      "name": "Example browser profile"
    },
    "createdAt": 1793318400000,
    "startedAt": null,
    "endedAt": null,
    "startAfter": null,
    "hasNodeErrors": false,
    "isolation": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Error responses

| HTTP | error.code | What to do |
|  --- | --- | --- |
| 409 | RPA_TEMPLATE_VERSION_CONFLICT | Check the receipt first to confirm that the request was not committed. Then read the template and decide on a new intent. |
| 409 | RPA_ENVIRONMENT_BUSY | The environment is busy or isolated, and the run cannot be queued. Query the status. |
| 409 | RPA_CATALOG_CHANGED | Check the receipt first. After you confirm that the request was not committed, refresh the catalog header. You can then recover with the original body/If-Match/key. |
| 409 | RPA_REQUEST_CONFLICT | The method/path/body/If-Match sent with the same key differs from the original intent. |
| 504 | RPA_REQUEST_TIMEOUT | This only means that the HTTP wait timed out. Check the original request receipt first. |


A same-key write replay keeps the ETag of the original response (if there was one; it may be stale). A receipt contains only data, without response headers. To continue editing, you must send a GET first. See [API conventions](/browser-rpa/api/common).

For common 400/401/403/404/429/5xx errors and failure fields, see [Errors and recovery](/browser-rpa/api/common#errors-and-recovery). Error response example (403):

```json
{
  "error": {
    "code": "RPA_PERMISSION_DENIED",
    "message": "The request Host or Origin is not allowed, or the current identity can't access the target environment",
    "retryable": false,
    "issues": [],
    "details": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

## Related

[Local API reference](/browser-rpa/local-api) · [API conventions](/browser-rpa/api/common) · [Data models](/browser-rpa/api/data-types) · [Workflow structure](/browser-rpa/api/workflow) · [Quickstart](/browser-rpa/quickstart)

If the browser environment cannot be resolved, the start request returns 422 RPA_ENVIRONMENT_UNAVAILABLE. Check the existing environment list and the client status first, and then run the preflight again. Both a successful start and a same-key replay keep `Location: /api/rpa/browser/v1/runs/<runId>`.