API REFERENCE
Execution API
The Execution API handles running agents with user input. It manages conversations, tool calls, streaming, and returns structured results.
Execute an Agent
POST /v1/agents/:id/execute
Request
{
"input": "What is the status of order #12345?",
"conversationId": "conv_abc123", // optional, for multi-turn
"stream": false, // set true for SSE
"memory": {
"session": { // optional session context
"userName": "Sarah",
"accountId": "ACC-789"
}
},
"memoryStores": ["mem_store123"], // optional persistent stores
"metadata": { // optional execution metadata
"source": "web-chat",
"sessionId": "sess_xyz"
}
}
FieldRequiredDescription
inputYesThe user's message or prompt
conversationIdNoContinue an existing conversation
streamNoEnable Server-Sent Events streaming (default: false)
memory.sessionNoKey-value pairs available to the agent
memoryStoresNoArray of persistent memory store IDs
metadataNoCustom metadata attached to the execution
Execution Response
Response (200)
{
"id": "exec_abc123def456",
"agentId": "agt_abc123",
"conversationId": "conv_def456",
"status": "completed",
"output": "I'd be happy to help you check on order #12345...",
"toolCalls": [
{
"id": "tc_ghi789",
"name": "lookup_order",
"parameters": { "orderId": "ORD-12345" },
"result": { "status": "shipped", "trackingNumber": "1Z999AA1..." },
"duration": 234
}
],
"usage": {
"inputTokens": 142,
"outputTokens": 89,
"totalTokens": 231,
"cacheReadTokens": 0,
"cacheWriteTokens": 50
},
"timing": {
"totalMs": 1234,
"firstTokenMs": 89,
"toolCallMs": 234
},
"metadata": {
"source": "web-chat"
},
"createdAt": "2026-03-15T10:30:00Z"
}
List Executions
GET /v1/executions
Returns a paginated list of executions. Filter by agent, status, or date range.
Query parameters
GET /v1/executions?agentId=agt_abc123&status=completed&limit=50
GET /v1/executions?after=exec_abc123&startDate=2026-03-01&endDate=2026-03-15
Retrieve an Execution
GET /v1/executions/:id
Returns the full execution object including output, tool calls, and usage.
Cancel an Execution
POST /v1/executions/:id/cancel
Cancel a running execution. Only works on executions with status "running". You are charged for tokens generated up to the cancellation point.
Response (200)
{
"id": "exec_abc123def456",
"status": "cancelled",
"output": "Partial response up to cancellation...",
"usage": {
"inputTokens": 142,
"outputTokens": 34,
"totalTokens": 176
}
}
Conversations
Conversations group multiple execution turns together. Each execution within a conversation shares the same context.
Get Conversation
GET /v1/conversations/:id
Response (200)
{
"id": "conv_abc123",
"agentId": "agt_def456",
"turns": [
{
"role": "user",
"content": "I need help with order #12345",
"timestamp": "2026-03-15T10:30:00Z"
},
{
"role": "assistant",
"content": "I'd be happy to help you...",
"toolCalls": [...],
"timestamp": "2026-03-15T10:30:02Z"
}
],
"tokenCount": 2341,
"turnCount": 6,
"createdAt": "2026-03-15T10:30:00Z",
"lastActiveAt": "2026-03-15T10:35:00Z"
}
Delete Conversation
DELETE /v1/conversations/:id
Permanently deletes the conversation and all its turns.
Note
Conversations are automatically deleted after 90 days of inactivity on the Starter plan, 180 days on Professional, and never on Enterprise.