Skip to main content
GET
/
api
/
v1
/
agent
/
status
curl 'https://agent.blackbox.ai/api/v1/agent/status?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "assistantMessageId": "msg_abc123xyz456",
  "error": null
}
This endpoint returns the raw internal status of an agent run identified by runId. Unlike the task status endpoint, this returns the internal status values directly (not mapped to external values) and also includes the assistantMessageId.

​
Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:
  1. Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your Dashboard
  3. From the Dashboard, create an API key to use with all Agent API requests
Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

​
Headers

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

​
Query Parameters

​
runId
string
required
The unique run identifier returned when the task was created.Example: runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Response Fields

​
runId
string | null
The run identifier. null if not found.
​
status
string | null
Internal status of the run.Possible values: queued, running, completed, failed, cancelled, interrupted, or null if not found.
​
assistantMessageId
string | null
ID of the assistant message being generated. null if not yet assigned or not found.
​
error
string | null
Error message if the run failed, null otherwise.
curl 'https://agent.blackbox.ai/api/v1/agent/status?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "assistantMessageId": "msg_abc123xyz456",
  "error": null
}

​
Error Codes

Status CodeErrorDescription
200SuccessStatus returned (may be null if run not found)
400Bad RequestMissing runId query parameter
401UnauthorizedInvalid or missing API key