List tasks
Check several tasks at once, or filter them by status and creation time: parameters, response and errors.
GET
https://api.nanoapi.ai/v1/tasksCheck several tasks at once (up to 20), or filter them by status and creation time. Every response uses the { code, message, data } envelope, see Response format.
Parameters
| Query parameter | Description |
|---|---|
ids | Up to 20 comma-separated task IDs, to check several tasks in one request. Other filters and pagination are then ignored. |
status | queued, running, succeeded or failed. |
created_after / created_before | Creation time range (ISO 8601). |
limit / starting_after | See Pagination. |
curl "https://api.nanoapi.ai/v1/tasks?ids=tk_01jb8z5q4w3e2r1t0y9u8i7o6p,tk_01jb8z7c2d4f6g8h0j2k4m6n8p" \
-H "Authorization: Bearer $NANOAPI_API_KEY"Response
On success you get 200 with a list as data:
{
"code": 200,
"message": "success",
"data": {
"object": "list",
"items": [
{
"object": "task",
"id": "tk_01jb8z7c2d4f6g8h0j2k4m6n8p",
"model": "genjutsu-1.0",
"status": "running",
"input": {
"mode": "motion_control",
"image_urls": ["https://example.com/person.png"],
"video_url": "https://example.com/walk.mp4",
"prompt": "",
"resolution": "720p"
},
"num_outputs": 1,
"outputs": [],
"billing": {
"currency": "USD",
"frozen": "2.73",
"charged": "0.00",
"refunded": "0.00",
"billed_seconds": null
},
"error": null,
"webhook_url": null,
"created_at": "2026-10-22T08:40:00Z",
"started_at": "2026-10-22T08:41:10Z",
"finished_at": null,
"elapsed_seconds": null
},
{
"object": "task",
"id": "tk_01jb8z5q4w3e2r1t0y9u8i7o6p",
"model": "genjutsu-1.0",
"status": "succeeded",
"input": {
"mode": "motion_control",
"image_urls": ["https://example.com/person.png"],
"video_url": "https://example.com/dance.mp4",
"prompt": "",
"resolution": "720p"
},
"num_outputs": 1,
"outputs": [
{
"index": 0,
"type": "video",
"url": "https://file.example.com/outputs/tk_01jb8z5q4w3e2r1t0y9u8i7o6p/0.mp4",
"preview_url": "https://file.example.com/outputs/tk_01jb8z5q4w3e2r1t0y9u8i7o6p/0_compressed.mp4"
}
],
"billing": {
"currency": "USD",
"frozen": "4.095",
"charged": "4.095",
"refunded": "0.00",
"billed_seconds": 15
},
"error": null,
"webhook_url": "https://example.com/hooks/nanoapi",
"created_at": "2026-10-22T08:30:00Z",
"started_at": "2026-10-22T08:31:05Z",
"finished_at": "2026-10-22T08:47:12Z",
"elapsed_seconds": 1032
}
],
"has_more": false
}
}- Every item in
itemsis a full task object, newest first. Match results byid, not by position. has_moreistruewhen there's another page, see Pagination.- IDs in
idsthat don't exist or aren't yours are left out, and an unknownstarting_afterreturns an empty list: neither returns404. - Reads are limited to 60 per 10 seconds, so check all the tasks you're waiting on in one request (Rate limits).
Errors
A failed request returns 4xx / 5xx. Only this one read failed; it says nothing about the tasks. For example, more than 20 ids:
{
"code": 400,
"message": "ids must contain 1 to 20 task ids.",
"error": {
"type": "invalid_request",
"param": "ids",
"details": null
},
"request_id": "rq_01jb8z9x2c4v6b8n0m1q3w5e7r"
}Branch on error.type; error.param names the parameter at fault.
error.type | Status | When | What to do |
|---|---|---|---|
invalid_request | 400 | A parameter is wrong: limit isn't 1–100; ids is empty or has more than 20 IDs (param is "ids"); status isn't queued / running / succeeded / failed; created_after / created_before isn't an ISO 8601 time with a time zone. | Fix the parameter named in param. |
invalid_api_key | 401 | The key is missing or malformed, doesn't exist, was deleted or has been reset. | Use a valid key. |
account_suspended | 403 | Your account has been suspended. | Contact support@nanoapi.ai. |
rate_limited | 429 | Too many reads: all read endpoints together (retrieving and listing tasks, the balance, products) allow 60 requests per 10 seconds per account, shared by all your keys (the website playground counts too). | Retry after Retry-After seconds. Pages count as reads too, so don't page through quickly. |
internal_error | 500 | Something went wrong on our side. | Reads have no side effects, so you can simply retry. |