Skip to main content
Batches

List Batch Tasks

GET /api/v1/forward/batches/{batch_id}/tasks Lists the status, result summary, error, artifacts, and usage for tasks in a Batch with pagination. You can call this endpoint while the Batch is in any state. It returns tasks only for a Batch owned by the current PAT user.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>

Path parameters

ParameterTypeRequiredDescription
batch_idstringYesBatch ID.

Query parameters

ParameterTypeRequiredDefaultDescription
statusstringNo-Filter by task status: pending, running, completed, failed, cancelled, or expired.
custom_idstringNo-Exact-match filter for the caller-defined task identifier. Only one value is supported. Returns an empty list when no match is found.
limitintegerNo20Page size. Maximum: 100.
after_idstringNo-Cursor for the next page. Pass the previous response's last_id. The cursor must belong to the current Batch.

Example request

curl -s -X GET 'https://api.qoder.com/api/v1/forward/batches/batch_completed001/tasks?limit=20' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Example response

HTTP 200 OK 
{
  "object": "list",
  "data": [
    {
      "custom_id": "task-001",
      "status": "completed",
      "started_at": "2026-08-06T14:01:03Z",
      "completed_at": "2026-08-06T14:03:41Z",
      "output_summary": "report generated",
      "usage": {
        "total_credits": 2.75
      },
      "artifacts": [
        {
          "file_id": "file_abc",
          "name": "report.xlsx",
          "size": 20480,
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        }
      ]
    },
    {
      "custom_id": "task-002",
      "status": "failed",
      "started_at": "2026-08-06T14:01:03Z",
      "completed_at": "2026-08-06T14:01:20Z",
      "error": {
        "code": "session_error",
        "message": "sandbox terminated unexpectedly"
      },
      "usage": {
        "total_credits": 0.5
      },
      "artifacts": []
    }
  ],
  "has_more": true,
  "first_id": "task-001",
  "last_id": "task-002"
}

Response fields

FieldTypeDescription
objectstringAlways list.
dataarrayBatch Task objects on the current page.
data[].custom_idstringCaller-defined task identifier and the public pagination cursor in the current version.
data[].statusstringTask status, using the same definitions as Batch request_counts.
data[].started_atstringStart time of the final persisted execution attempt, in RFC 3339 UTC. Omitted if the task has not started.
data[].completed_atstringTask completion time, in RFC 3339 UTC. Omitted if the task is not complete.
data[].output_summarystringFinal response text, up to 500 Unicode characters. Omitted when there is no result.
data[].errorobjectReturned only for failed tasks. Contains code and message.
data[].artifactsarrayDelivered artifacts. Returns an empty array when there are none.
data[].usageobjectUsage for the final or current CAS Session. Omitted if CAS has not returned valid usage.
data[].usage.total_creditsnumberCumulative CAS Session Credit usage. It is not a token count or currency amount. Explicit zero values are preserved.
first_idstringcustom_id of the first task on the current page.
last_idstringcustom_id of the last task on the current page.
has_morebooleanWhether more tasks are available.
A transient error retry creates a new CAS Session for the task. Therefore, usage represents only the final or current Session and does not accumulate usage from replaced historical Sessions.

Error codes

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_requeststatus, limit, or after_id is invalid.
404not_found_errorbatch_not_foundBatch does not exist, belongs to another user, or its result files have completed the 30-day cleanup.
401authentication_errorauthentication_requiredPAT or SAT is invalid or expired.

Notes

  • When has_more=true, pass last_id unchanged as after_id in the next request.
  • Artifact downloads reuse the Files API. There is no Batch-specific artifact download endpoint.

Get a batch

Get the output file

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference