Sign in
Tasks v1

Create Task Run

Initiates a task run.

Returns immediately with a run object in status 'queued'.

Beta features can be enabled by setting the 'parallel-beta' header.

post/v1/tasks/runs

Request body

metadataobject nullable

User-provided metadata stored with the run. Keys and values must be strings with a maximum length of 16 and 512 characters respectively.

previous_interaction_idstring nullable

Interaction ID to use as context for this request.

processorstring required

Processor to use for the task.

Example request

{
  "processor": "base",
  "source_policy": {
    "after_date": "2024-01-01",
    "exclude_domains": [
      "reddit.com",
      "x.com",
      ".ai"
    ],
    "include_domains": [
      "wikipedia.org",
      "usa.gov",
      ".edu"
    ]
  },
  "task_spec": {
    "input_schema": {
      "json_schema": {
        "additionalProperties": false,
        "properties": {
          "gdp": {
            "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'",
            "type": "string"
          }
        },
        "required": [
          "gdp"
        ],
        "type": "object"
      }
    },
    "output_schema": {
      "json_schema": {
        "additionalProperties": false,
        "properties": {
          "gdp": {
            "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'",
            "type": "string"
          }
        },
        "required": [
          "gdp"
        ],
        "type": "object"
      }
    }
  }
}

Response

Successful Response

created_atstring nullable required

Timestamp of the creation of the task, as an RFC 3339 string.

interaction_idstring required

Identifier for this interaction. Pass this value as previous_interaction_id to reuse context for a future request.

is_activeboolean required

Whether the run is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}.

metadataobject nullable

User-provided metadata stored with the run.

modified_atstring nullable required

Timestamp of the last modification to the task, as an RFC 3339 string.

processorstring required

Processor used for the run.

run_idstring required

ID of the task run.

status'queued' | 'action_required' | 'running' | 'completed' | 'failed' | 'cancelling' | 'cancelled' required

Status of the run.

taskgroup_idstring nullable

ID of the taskgroup to which the run belongs.

Example response

{
  "created_at": "2025-04-24T18:56:22.513132Z",
  "interaction_id": "trun_e0083b6aac0544eb8686e8d2a76533d2",
  "metadata": {},
  "modified_at": "2025-04-24T18:56:22.513132Z",
  "processor": "base",
  "run_id": "trun_e0083b6aac0544eb8686e8d2a76533d2",
  "status": "queued",
  "warnings": []
}

Changes