curl 'https://agent.blackbox.ai/api/v1/agent/status?runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/agent/status?runId=${RUN_ID}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(`Status: ${data.status}`);
console.log(`Message ID: ${data.assistantMessageId}`);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
"https://agent.blackbox.ai/api/v1/agent/status",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"runId": RUN_ID},
)
data = response.json()
print(f"Status: {data['status']}")
print(f"Message ID: {data['assistantMessageId']}")
{
"runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "running",
"assistantMessageId": "msg_abc123xyz456",
"error": null
}
{
"runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"assistantMessageId": "msg_abc123xyz456",
"error": null
}
{
"runId": null,
"status": null,
"assistantMessageId": null,
"error": null
}
{
"error": "runId query parameter is required"
}
Logs & Streaming
Agent Run Status
Check the current status of a Claude Agent run by runId. Checks live in-memory state first, falls back to the database.
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'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/agent/status?runId=${RUN_ID}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(`Status: ${data.status}`);
console.log(`Message ID: ${data.assistantMessageId}`);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
"https://agent.blackbox.ai/api/v1/agent/status",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"runId": RUN_ID},
)
data = response.json()
print(f"Status: {data['status']}")
print(f"Message ID: {data['assistantMessageId']}")
{
"runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "running",
"assistantMessageId": "msg_abc123xyz456",
"error": null
}
{
"runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"assistantMessageId": "msg_abc123xyz456",
"error": null
}
{
"runId": null,
"status": null,
"assistantMessageId": null,
"error": null
}
{
"error": "runId query parameter is required"
}
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:- Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
- Once provisioning completes, you will be redirected to your Dashboard
- From the Dashboard, create an API key to use with all Agent API requests
sk-xxxxxxxxxxxxxxxxxxxxxx
Headers
string
required
API Key of the form
Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560Query Parameters
string
required
The unique run identifier returned when the task was created.Example:
runId=a1b2c3d4-e5f6-7890-abcd-ef1234567890Response Fields
string | null
The run identifier.
null if not found.string | null
Internal status of the run.Possible values:
queued, running, completed, failed, cancelled, interrupted, or null if not found.string | null
ID of the assistant message being generated.
null if not yet assigned or not found.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'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/agent/status?runId=${RUN_ID}`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(`Status: ${data.status}`);
console.log(`Message ID: ${data.assistantMessageId}`);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
"https://agent.blackbox.ai/api/v1/agent/status",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"runId": RUN_ID},
)
data = response.json()
print(f"Status: {data['status']}")
print(f"Message ID: {data['assistantMessageId']}")
{
"runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "running",
"assistantMessageId": "msg_abc123xyz456",
"error": null
}
{
"runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"assistantMessageId": "msg_abc123xyz456",
"error": null
}
{
"runId": null,
"status": null,
"assistantMessageId": null,
"error": null
}
{
"error": "runId query parameter is required"
}
Error Codes
| Status Code | Error | Description |
|---|---|---|
| 200 | Success | Status returned (may be null if run not found) |
| 400 | Bad Request | Missing runId query parameter |
| 401 | Unauthorized | Invalid or missing API key |