# Calling tasks

> The ways to submit a task and learn that its job has ended, and when to use each.

Every task call is `POST /v1/tasks/{name}` and starts a job. What differs is how you hear back: you
poll the job, you hold the submit open until it ends, or we call you. The recommended way is to
submit and poll, or to submit and receive a webhook.

| Method | How it works | When |
|---|---|---|
| **Submit and poll** (recommended) | the submit answers `202` at once; read `status_url` until `lifecycle` is `terminal`, then `result_url` | the default for every task |
| **Wait** (`Prefer: wait=N`) | the submit holds its answer up to `N` seconds; a job that ends in time answers `200` with its result | short jobs, scripts, tests |
| **Webhook per job** (`?webhook_url=`) (recommended) | we `POST` the job's terminal event to your URL | long jobs, when your server can receive a request |
| **Registered webhook endpoints** | an endpoint registered in **Panel › Developers › Webhooks** receives the events of every job started with your keys | many jobs; progress events |

The methods combine: a `Prefer: wait` submit that runs out of time answers `202`, and you poll from
there; a job with a webhook can still be polled.

## Next steps

::::cards
:::card{title="Asynchronous jobs" href="/task-apis/calling-tasks/asynchronous-jobs"}
Submit, poll, read the result, cancel.
:::
:::card{title="Synchronous" href="/task-apis/calling-tasks/synchronous"}
Wait for a short job on the submit call.
:::
:::card{title="Webhooks" href="/task-apis/calling-tasks/webhooks"}
Be called when a job ends.
:::
:::card{title="Client setup" href="/task-apis/calling-tasks/client-setup"}
Set up the HTTP client every method uses.
:::
::::