Skip to main content
POST
/
api
/
v2
/
async
/
agent
/
run
Run Agent
curl --request POST \
  --url https://app.octavehq.com/api/v2/async/agent/run \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "agentOId": "ca_...",
  "companyDomain": "example.com",
  "companyName": "Example",
  "crmAccountId": "<string>",
  "runtimeContext": {
    "user": {
      "oId": "user_123"
    }
  },
  "includeFullAnnotation": true,
  "callbackUrl": "https://example.com/api/callbacks/unique-id",
  "experimentOId": "ae_..."
}
'
{
  "status": "pending",
  "requestId": "requestId",
  "message": "Additional information",
  "agentOId": "ca_..."
}

Authorizations

​
api_key
string
header
required

Headers

​
x-request-source
string

Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary.

Example:

"some-source"

​
x-external-request-id
string

External Request ID. Add this header to identify the request from the client for better tracking and debugging.

Example:

"external-request-id"

Body

application/json

Run agent by given input, the input is different for each agent

​
agentOId
string
required

Agent OId

Example:

"ca_..."

​
companyDomain
string | null

Company domain to enrich

Example:

"example.com"

​
companyName
string | null

Company name to enrich

Example:

"Example"

​
crmAccountId
string | null
​
runtimeContext
any · null · null · null

Runtime context

Example:
{ "user": { "oId": "user_123" } }
​
includeFullAnnotation
boolean

If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size.

​
callbackUrl
string<uri>

Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.

Example:

"https://example.com/api/callbacks/unique-id"

​
experimentOId
string

Experiment OId

Example:

"ae_..."

Response

Agent data

​
status
enum<string>
required

Status

Available options:
pending,
completed,
failed
Example:

"pending"

​
requestId
string
required

Request ID

Example:

"requestId"

​
message
string | null

Message

Example:

"Additional information"

​
agentOId
string

The Agent OId that was selected/used for the run

Example:

"ca_..."