Skip to main content
Poll the dispatcher for the current state of a task started by /tasks/submit. Returns whatever’s known right now — pending, running, or one of three terminal states (completed, failed, cancelled). For real-time delivery (server-pushed state changes instead of client-pulled polls), use GET /v1/tasks/stream/{task_id} (SSE) or a callback_url registered on submit.

​
When to use

  • Cheap polling loop — /tasks/query is free; call it on a cadence matched to the task’s estimated_seconds
  • Reconciling after process restart — your client died, you only have the out_task_id in your DB; query by that to recover the current state
  • Final output retrieval — once status is completed, the output array holds the generated images / videos

​
Request

​
By task_id

curl https://llm.bytespike.ai/v1/tasks/query \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"task_id": "task_01HQX9F2P6Y8VEX3CRZ8GXJVD9"}'

​
By out_task_id (idempotency key)

curl https://llm.bytespike.ai/v1/tasks/query \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"out_task_id": "my-render-2026-05-25-001"}'

​
Body

FieldTypeRequiredNotes
task_idstringone-ofServer-generated ULID returned by /tasks/submit.
out_task_idstringone-ofThe idempotency key you supplied on submit.
Exactly one of task_id or out_task_id is required. Sending both returns 400 invalid_param.

​
Response

​
While running

{
  "task_id": "task_01HQX9F2P6Y8VEX3CRZ8GXJVD9",
  "out_task_id": "my-render-2026-05-25-001",
  "status": "running",
  "estimated_credits": 1.50,
  "estimated_seconds": 35
}

​
After completion

{
  "task_id": "task_01HQX9F2P6Y8VEX3CRZ8GXJVD9",
  "out_task_id": "my-render-2026-05-25-001",
  "status": "completed",
  "credits_used": 1.47,
  "output": [
    {
      "type": "video",
      "url": "https://cdn.bytespike.ai/multimodal/sora-2/2026-05-25/01HQX9F2P6Y8VEX3CRZ8GXJVD9.mp4",
      "duration_seconds": 8,
      "width": 1920,
      "height": 1080
    }
  ]
}

​
After failure

{
  "task_id": "task_01HQX9F2P6Y8VEX3CRZ8GXJVD9",
  "out_task_id": "my-render-2026-05-25-001",
  "status": "failed",
  "error_code": "content_policy_violation",
  "error_message": "The prompt was rejected under content policy."
}

​
Response fields

FieldTypeNotes
task_idstringAlways present.
out_task_idstringEchoes back if you supplied one on submit.
statusstringpending, running, completed, failed, cancelled.
estimated_creditsnumberPre-flight cost estimate. Present from pending onward, cleared once credits_used is set.
estimated_secondsintegerPre-flight ETA.
credits_usednumberFinal billed credits. Present only on completed. Failed and cancelled tasks are free (field absent).
outputarrayArray of result objects. Shape depends on the model. Present only on completed.
error_codestringMachine-readable error tag. Present only on failed.
error_messagestringHuman-readable error. Present only on failed.

​
Polling cadence

Match your poll interval to the model’s estimated_seconds from the submit response. A good default for video: 
import time, requests

eta = submit_resp.json()["estimated_seconds"] or 30
sleep_for = max(2, eta // 6)  # poll ~6 times across the expected duration

while True:
    r = requests.post(
        "https://llm.bytespike.ai/v1/tasks/query",
        headers={"Authorization": f"Bearer {os.environ['BYTESPIKE_API_KEY']}"},
        json={"task_id": task_id},
    )
    state = r.json()
    if state["status"] in ("completed", "failed", "cancelled"):
        break
    time.sleep(sleep_for)
For zero-polling delivery, prefer callback_url (set on submit) or the SSE stream endpoint.

​
Errors

HTTPcodeWhen
400invalid_paramBoth task_id and out_task_id sent, or both empty.
401invalid_api_keyMissing / revoked key.
404task_not_foundNo task matches the supplied identifier — or the task belongs to a different API key.

​
Pricing

Free. Polling does not consume credits. Only completed tasks bill (via the original submit). Re-querying a completed task as many times as you like is zero-cost.

​
Next