Get account task
Read task metadata and billing status by task ID
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 a task's persisted metadata and confirmable billing by task_id, for tracking a generation task's progress and cost. Generation results, prompts, and replay data are not returned. Queries do not refresh task status and do not trigger settlement or webhooks.
Only task_id is accepted — there is no client_business_id fallback. Tasks belonging to others or that do not exist return 404.
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
AuthorizationstringheaderrequiredUse Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.
Request parameters
task_idstringpathrequiredPlatform task ID, not a business ID. Leading or trailing whitespace and control characters are rejected.
Constraints: minLength=1; maxLength=191.
Request examples
requestExample
curl --request GET \
--url 'https://api.toapis.com/api/v1/tasks/task_example_01' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/tasks/task_example_01",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.toapis.com/api/v1/tasks/task_example_01");
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.
codeintegerNumeric result code; 0 means success.
messagestringResponse message; empty on success. Error messages are localized.
dataobjectResult object for this query.
data.idstringPlatform task ID used for task details, not a business ID.
data.client_business_idstring | nullBusiness ID saved when creating the task, distinct from the platform task ID. null when unknown or inapplicable.
data.api_key_idstring | nullAssociated model API key ID; null when no key is associated.
data.typestringTask type. Values: image, video, music, other.
data.modelstringModel identifier.
data.statusstringPublic task state. Video storage or settlement still in progress remains processing. Values: pending, processing, completed, failed.
data.progressintegerTask progress percentage, from 0 to 100.
data.created_atstring | nullCreation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.finished_atstring | nullConfirmed terminal task time; null while processing or when not confirmed. RFC 3339 timestamp with a timezone.
data.billingobject | nullConfirmed task billing information; null when it cannot be confirmed.
data.billing.statusstringTask billing state. Amounts are omitted for pending; confirmed states are settled or refunded. Values: pending, settled, refunded.
data.billing.creditsstringConfirmed task billing amount in credits. Omitted for pending. Returned as a decimal string to preserve precision.
data.billing.cost_usdstringConfirmed task billing amount in USD. Omitted for pending. Returned as a decimal string to preserve precision.
Response examples
responseExample
{
"code": 0,
"message": "",
"data": {
"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"
}
}
}