Skip to main content
POST
/
api
/
runs
Run Agent
curl --request POST \
  --url https://api.example.com/api/runs \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "model": "o3",
  "provider": "openai",
  "wait_for_completion": true,
  "webhook_url": "<string>",
  "response_format": "text",
  "json_schema": "<string>",
  "use_cached_workflow": true,
  "cached_workflow": {}
}
'
{
  "task_id": 123,
  "task_run_id": 123,
  "history": [
    {
      "description": "<string>",
      "actions": [
        {
          "name": "<string>",
          "params": {},
          "is_done": true,
          "success": true,
          "extracted_content": "<string>",
          "error": "<string>",
          "include_in_memory": true
        }
      ]
    }
  ],
  "result": "<unknown>",
  "is_done": true,
  "is_successful": true,
  "status": "in_progress"
}

Body

application/json
​
prompt
string
required

The task to be performed by the agent

Minimum string length: 3
​
model
string
default:o3
​
provider
enum<string>
default:openai
Available options:
openai,
deepseek,
anthropic,
google,
groq,
mistral,
together
​
wait_for_completion
boolean | null
default:true

Whether to wait for the task to complete before returning the response. If false, the task will be executed in the background and the response will contain only the task ID.

​
webhook_url
string | null

URL to send webhook notification when task is complete

​
response_format
string | null
default:text

Whether to return the result as text or JSON

​
json_schema

The JSON schema for the task result

​
use_cached_workflow
boolean | null

Internal field: whether to use cached workflow

​
cached_workflow
Cached Workflow · object

Internal field: the cached workflow data

Response

Successful Response

Represents the complete response from the agent.

​
task_id
integer | null

The ID of the task

​
task_run_id
integer | null

The ID of the task run

​
history
HistoryItem · object[] | null

List of steps in the history

​
result
any | null

The final result of the agent's task

​
is_done
boolean | null

Whether the agent has completed its task

​
is_successful
boolean | null

Whether the agent was successful in completing its task

​
status
enum<string>
default:in_progress

The status of the agent's task

Available options:
success,
failure,
in_progress