What are Tasks

A task — also called a request in the API — is a single run of a model. Submitting one returns an ID you use to track it.

Lifecycle

created → processing → completed | failed

Status	Meaning
created	Accepted, priced, and queued
processing	A worker is running it against an upstream provider
completed	Finished successfully; outputs is populated
failed	Finished with an error; code and error explain why

completed and failed are terminal — once you see either, stop polling. Provider retries happen inside a single task, so a task that recovers from an upstream failure keeps the same ID and never surfaces as failed.

Submit Response

Submitting returns a minimal acknowledgement, not a result:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "created",
  "estimated_duration": 52
}

Field	Description
id	Task ID; use it to poll or to correlate a webhook
status	Always created here
estimated_duration	Seconds, from the median runtime of recent runs of the same model and channel. null when there isn't enough history

Add ?sync=true to skip this and get the full result in the same response instead.

Result Object

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "completed",
  "code": 0,
  "input": {
    "prompt": "A cat wearing a space suit",
    "aspect_ratio": "16:9"
  },
  "outputs": ["https://storage.example.com/output.png"],
  "timings": {
    "queue_wait": 427,
    "celery_init": 2054,
    "api_call": 23068,
    "save": 1902,
    "run_overhead": 679,
    "total": 28131
  },
  "error": null,
  "created_at": "2026-03-28T07:50:42"
}

Field	Description
id	Task ID
model	Model slug that ran
status	Current status
code	0 on success, otherwise a task error code
input	The parameters you submitted
outputs	Array of output URLs; empty unless completed
timings	Per-stage durations in milliseconds
error	Error message, null on success
created_at	When the task was created

For speech-to-text, outputs holds the transcribed text rather than a URL.

Timings

All values are milliseconds:

Stage	What it measures
queue_wait	Time between submission and a worker picking it up
celery_init	Worker startup before the model call
api_call	Time spent at the upstream provider
save	Persisting outputs to storage
run_overhead	Remaining internal processing
total	End-to-end duration

api_call is the number to watch when comparing models or channels — the rest is platform overhead.

Retrieving a Task

Poll

curl "https://api.get3w.com/v1/requests/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

While the task is still running you get a short response plus a Retry-After: 3 header:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "processing"
}

Poll every 3–5 seconds. See Async Mode for a complete loop.

Webhook

Pass ?webhook=<your-url> at submit time and the same result payload is POSTed to you when the task finishes. See How to Use Webhooks.

Sync

Pass ?sync=true at submit time and the request blocks until the task is done, returning the result directly. See Get Started with API.

Retention

Task records are kept for 7 days. Output files stored on Get3W are kept for the current and previous calendar month, then removed. Since the window is measured in whole calendar months, a file created late in a month has a shorter effective lifetime than one created early — download anything you need to keep rather than relying on a fixed number of days.

If you attach your own cloud storage to an API key, outputs are written there and retention is under your control.

Failures and Billing

A task is priced up front and your balance is checked before it is queued — an underfunded request is rejected with 402 and never runs. Charges are settled after execution, so work that never reached a provider is not billed for the model call.

Next Steps

• How Get3W Works — Request flow and provider routing
• What are Account Tiers — How your tier affects task pricing
• Error Codes — What each code means