---
title: "Run a connector"
method: POST
path: "/v1beta/runs"
tags: ["Runs"]
---

# Run a connector

`POST /v1beta/runs`

## Request

- Base URL: `https://api.indices.io`
- URL: `https://api.indices.io/v1beta/runs`
- Auth: HTTP bearer

Execute a connector. By default the call blocks until the run finishes. Pass `async: true` to return immediately, in which case you should poll `GET /runs` to retrieve the result once it's ready.

## Request body

- CreateRunRequest
  - `connector_id` string, required: ID of the connector to execute.
  - `arguments` object: Arguments to pass to the connector. Optional if the connector does not require any arguments.
  - `secret_bindings` object: Mapping of secret slot names to the IDs of saved, user-owned secrets. Each of the connector's required_secrets must appear here or in secret_values, but not both.
  - `secret_values` object: Mapping of secret slot names to secret values supplied directly for this run, instead of referencing a saved secret. Use a login shape ({username, password, totp_secret?}) for login slots and a string shape ({value}) for string slots. Values are not persisted.
  - `proxy_settings` union: Proxy for the network traffic of this run. If you do not set it, a setting is automatically determined by the platform.
    - IspProxy
      - `type` 'isp'
      - `location` 'us', required
    - ResidentialProxy
      - `type` 'residential'
      - `location` 'at' | 'be' | 'ca' | 'ch' | 'de' | 'dk' | 'es' | 'fi' | 'fr' | 'gb' | 'ie' | 'it' | 'lu' | 'mx' | 'nl' | 'no' | 'pt' | 'se' | 'us', required
  - `async` boolean: When true, return immediately with a pending run; poll retrieveRun for the result. Results above 1,000,000 UTF-8 JSON bytes are discarded and finish with result_too_large. Retry those requests with async=false to receive the result directly.
  - `max_timeout_s` integer: Maximum execution time in seconds before the run is timed out.

## Response `200`

Successful response

- Run
  - `id` string, required: Unique identifier for the object.
  - `connector_id` string, required: ID of the connector executed in this run.
  - `connector_version` integer, required: Version of the connector executed in this run. Runs pin the version that was newest when they were created.
  - `arguments` object, required: Arguments in this run for the connector's input parameters.
  - `secret_bindings` object: Secrets to use for this run. This dict must be a mapping of secret slot names to secret IDs.
  - `status` 'pending' | 'running' | 'success' | 'connector_error' | 'timed_out' | 'result_too_large' | 'internal_error', required
  - `result` object, nullable, required: Execution result of the run, matching the connector's output schema. Synchronous requests return successful results up to the 100 MB execution limit. Only results of at most 1,000,000 UTF-8 JSON bytes are stored. Larger results are returned once to the synchronous caller and are null on later retrieval. If delivery fails, the result cannot be retrieved later.
  - `result_stored` boolean, required: Whether the result is retained for later retrieval.
  - `result_size_bytes` integer, nullable, required: Size of the executor's serialized result in UTF-8 bytes, when known.
  - `error` RunError, required
    - `type` string, required: Machine-readable failure type: `auth_required`, `invalid_input`, `site_unavailable`, `anti_bot`, `site_changed`, `internal_error`, `crash`, or `unhandled`.
    - `message` string, required: Human-readable description of the failure.
    - `retryable` boolean, nullable, required: Whether retrying the run with the same arguments is expected to succeed. Null when unknown.
    - `exception` string, nullable, required: Exception class name, when the failure came from a raised exception.
    - `details` object, nullable, required: Structured context reported by the connector.
  - `has_logs` boolean, required: Whether the run has associated logs
  - `created_at` string, date-time, required: Timestamp when the object was created.
  - `finished_at` string, date-time, nullable, required: Timestamp when the object was last updated.

## Other responses

- `202`: Async run accepted; poll `get /runs` until it reaches a terminal status.
- `422`: Validation error

---

[API](https://skmtc.dev/indices/apis/indices-api.md) · [All operations](https://skmtc.dev/indices/apis/indices-api/llms.txt) · [OpenAPI document](https://skmtc.dev/indices/apis/indices-api/revisions/e0f2742c126c?raw)