Requests
Read the status and result of a request, or cancel it.
A request belongs to the account that submitted it: any key of that account can read or cancel it, and an id of another account (or one that is not a UUID) answers 404 NOT_FOUND. Final results are kept for 30 days.
| Method | Path | Summary |
|---|---|---|
GET | /v1/requests/{request_id} | Status and result of a request (owner only). |
GET | /v1/requests/{request_id}/status | Alias of GET /v1/requests/{request_id}. |
POST | /v1/requests/{request_id}/cancel | Ask to cancel a request. |
#GET /v1/requests/{request_id}
Status and result of a request (owner only).
Authentication: Authorization: Key <key>.
Statuses: queued, running (open); completed, partial, failed, cancelled (final). See Requests & lifecycle.
#Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
request_id | string | yes | The request_id returned by a submit call. |
#Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
wait | integer (min 0, max 60) | no | Long-poll up to N seconds (integer 0-60) for a terminal status. |
#Responses
| Status | Description | Body |
|---|---|---|
200 | Request | Request |
400 | INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN | Error |
401 | UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key) | Error |
404 | MODEL_NOT_FOUND or NOT_FOUND | Error |
429 | RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header) | Error |
500 | INTERNAL_ERROR (an unexpected server error) | Error |
#Example
Request
curl "https://api-live.aitopia.ai/v1/requests/0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10?wait=30" \
-H "Authorization: Key $AITOPIA_KEY"Response 200
{
"request_id": "0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10",
"status": "completed",
"endpoint": "google/nano-banana-2",
"created_at": "2026-10-23T10:00:00.000Z",
"completed_at": "2026-10-23T10:00:14.000Z",
"credits_estimated": 4,
"output": {
"images": [
{
"url": "https://cdn.aitopia.ai/...",
"content_type": "image/png"
}
],
"videos": [],
"audio": [],
"files": []
},
"status_url": "https://api-live.aitopia.ai/v1/requests/0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10",
"result_url": "https://api-live.aitopia.ai/v1/requests/0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10",
"cancel_url": "https://api-live.aitopia.ai/v1/requests/0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10/cancel"
}#GET /v1/requests/{request_id}/status
Alias of GET /v1/requests/{request_id}.
Authentication: Authorization: Key <key>.
#Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
request_id | string | yes | The request_id returned by a submit call. |
#Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
wait | integer (min 0, max 60) | no | Long-poll up to N seconds (integer 0-60) for a terminal status. |
#Responses
| Status | Description | Body |
|---|---|---|
200 | Request | Request |
400 | INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN | Error |
401 | UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key) | Error |
404 | MODEL_NOT_FOUND or NOT_FOUND | Error |
429 | RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header) | Error |
500 | INTERNAL_ERROR (an unexpected server error) | Error |
#Example
Request
curl "https://api-live.aitopia.ai/v1/requests/0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10/status" \
-H "Authorization: Key $AITOPIA_KEY"#POST /v1/requests/{request_id}/cancel
Ask to cancel a request.
Authentication: Authorization: Key <key>.
cancel is cancelled, cancellation_requested, cannot_cancel (with will_be_charged when known) or already_terminal. Only model runs can be cancelled; edits and other background media runs answer cannot_cancel.
#Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
request_id | string | yes | The request_id returned by a submit call. |
#Responses
| Status | Description | Body |
|---|---|---|
200 | Cancel verdict | Cancel |
401 | UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key) | Error |
404 | MODEL_NOT_FOUND or NOT_FOUND | Error |
429 | RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header) | Error |
500 | INTERNAL_ERROR (an unexpected server error) | Error |
502 | UPSTREAM_5XX, or UPSTREAM_UNCERTAIN (the run may have started: check the request_id in the body and your balance before retrying) | Error |
#Example
Request
curl -X POST "https://api-live.aitopia.ai/v1/requests/0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10/cancel" \
-H "Authorization: Key $AITOPIA_KEY"Response 200
{
"request_id": "0d6f3c1e-5b7a-4c2e-9d1f-2a8b6e4c9f10",
"cancel": "cannot_cancel",
"will_be_charged": true
}