ToAPIsToAPIs
Tasks

List account tasks

Page or batch query your persisted tasks

GET
/api/v1/tasks

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

See Access for authentication, pagination, and errors.

Behavior

Returns the account's persisted tasks page by page, for checking generation task status and billing. The default range is the last 24 hours, up to 31 days, ordered by internal ID descending. ids batch lookups are not paginated and their meta omits from/to.

Only persisted task metadata is returned — no generation result URLs or prompts. Queries do not poll upstream and do not trigger settlement, refunds, or webhooks. While video transfer or settlement is incomplete, status remains processing with finished_at=null.

Before returning billing data the endpoint runs a confirmability check and returns 503 rather than unreliable data when it fails. A task whose billing cannot be confirmed individually shows billing=null.

While billing.status=pending the amount fields are omitted, becoming settled or refunded afterwards.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.

Request parameters

fromstringquery

Inclusive start in RFC 3339 with a timezone. Provide together with to.

Constraints: date-time.

tostringquery

Exclusive end in RFC 3339 with a timezone. Must be later than from.

Constraints: date-time.

modelstringquery

Exact model identifier match.

Constraints: maxLength=191.

cursorstringquery

Pass the previous next_cursor unchanged and keep the same filters. Restart when filters change.

Constraints: maxLength=2048.

limitintegerquerydefault: 20

Maximum number of items per page.

Constraints: minimum=1; maximum=50; Default: 20.

typestringquery

Task type. The status query parameter is not supported.

Constraints: image, video, music, other.

client_business_idstringquery

Exact business ID. Leading or trailing whitespace and control characters are rejected.

Constraints: minLength=1; maxLength=191.

idsstringquery

Comma-separated platform task IDs, at most 20 raw entries. Mutually exclusive with every other query parameter. Visible IDs are deduplicated in first-seen order; missing or unauthorized tasks are omitted.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/tasks?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&type=video&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/tasks",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "type": "video",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/tasks");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "type": "video",
  "limit": "20"
}).toString();

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictional data and assume credits_per_usd="100". Use the conversion rate returned by the API.

Results are in data.items. Paginate with has_more and next_cursor; the final cursor is null. No total count is returned.

codeinteger

Numeric result code; 0 means success.

messagestring

Response message; empty on success. Error messages are localized.

dataobject

Result object for this query.

data.itemsobject[]

Records on this page; [] when empty.

data.items[].idstring

Platform task ID used for task details, not a business ID.

data.items[].client_business_idstring | null

Business ID saved when creating the task, distinct from the platform task ID. null when unknown or inapplicable.

data.items[].api_key_idstring | null

Associated model API key ID; null when no key is associated.

data.items[].typestring

Task type. Values: image, video, music, other.

data.items[].modelstring

Model identifier.

data.items[].statusstring

Public task state. Video storage or settlement still in progress remains processing. Values: pending, processing, completed, failed.

data.items[].progressinteger

Task progress percentage, from 0 to 100.

data.items[].created_atstring | null

Creation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].finished_atstring | null

Confirmed terminal task time; null while processing or when not confirmed. RFC 3339 timestamp with a timezone.

data.items[].billingobject | null

Confirmed task billing information; null when it cannot be confirmed.

data.items[].billing.statusstring

Task billing state. Amounts are omitted for pending; confirmed states are settled or refunded. Values: pending, settled, refunded.

data.items[].billing.creditsstring

Confirmed task billing amount in credits. Omitted for pending. Returned as a decimal string to preserve precision.

data.items[].billing.cost_usdstring

Confirmed task billing amount in USD. Omitted for pending. Returned as a decimal string to preserve precision.

data.has_moreboolean

Whether another page is available.

data.next_cursorstring | null

Pass this cursor unchanged with the same filters. It is null on the last page.

data.metaobject

Metadata describing the source, query scope, and accounting basis.

data.meta.scopestring

Ownership scope of the query: the authenticated account itself.

data.meta.sourcestring

Data source. Local configuration or ledger snapshots do not imply live Stripe state.

data.meta.consistencystring

Consistency model. eventual means records can be updated later.

data.meta.fromstring

Inclusive start of the query time range.

data.meta.tostring

Exclusive end of the query time range.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "task_example_01",
        "client_business_id": "order_example_01",
        "api_key_id": "42",
        "type": "video",
        "model": "example-video-model",
        "status": "completed",
        "progress": 100,
        "created_at": "2026-11-01T08:00:00Z",
        "finished_at": "2026-11-01T08:01:00Z",
        "billing": {
          "status": "settled",
          "credits": "2",
          "cost_usd": "0.02"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "source": "persisted_tasks",
      "consistency": "eventual",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z"
    }
  }
}