# Get a task

> GET /v1/tasks/{id}: Get a task. Noptcha API reference.

Source: https://noptcha.com/docs/api-reference/get-task/

GET https://api.noptcha.com/v1/tasks/{id}

Native API (v1). [Guide](https://noptcha.com/docs/native-api.md). Operation ID `getTask`.

Returns the task: 200 when final, 202 while processing. With `?wait=N` (or `Prefer: wait=N`) this is a long poll of up to N seconds (at most 90) that returns as soon as the task completes. Unknown and expired tasks, tasks of other organizations, and sandbox tasks asked with a live key (or the reverse) are `404`.

One task may be polled 5 times per second (bursts of 10); a long poll counts once. Over the limit: `429 rate_limited` with `Retry-After` and `RateLimit-Policy: "poll";q=10;w=2`. When the server already has too many waiting requests, a long poll returns `processing` at once (without `Preference-Applied`); wait a second before asking again.

## Request

Authentication: `Authorization: Bearer <key>` ([Keys](https://noptcha.com/docs/authentication.md)).

| Parameter | In | Description |
| --- | --- | --- |
| `id`  required  | path |  Task ID (decimal digits; the same number as the compatibility API's `taskId`).  string · pattern: ^\[0-9\]{1,16}$ · e.g. 7259140378796032  |
| `wait`  optional  | query |  Seconds to wait for the result (capped at 90). Takes precedence over `Prefer: wait`. Values that are not a non-negative integer are ignored.  integer · ≥ 0  |
| `Prefer`  optional  | header |  `wait=N`: wait up to N seconds (capped at 90) for the result, RFC 7240.  string · e.g. wait=60  |

## Responses

### 200

The task is final.

Headers: `Location` (optional), `Noptcha-Request-Id`, `Preference-Applied` (optional).

Content: `application/json`

| Field | Type | Description |
| --- | --- | --- |
| `completed_at`  optional  | `string` |  When the task became final; absent while processing.  format: date-time · pattern: ^\[0-9\]{4}-\[0-9\]{2}-\[0-9\]{2}T\[0-9\]{2}:\[0-9\]{2}:\[0-9\]{2}\\.\[0-9\]{3}Z$  |
| `cost`  required  | `object` |  What the task cost (zero unless solved and charged).  |
| `cost.amount`  required  | `string` |  Decimal US dollars with 6 places.  pattern: ^-?\[0-9\]+\\.\[0-9\]{6}$  |
| `cost.currency`  required  | `const "USD"` |  |
| `created_at`  required  | `string` |  format: date-time · pattern: ^\[0-9\]{4}-\[0-9\]{2}-\[0-9\]{2}T\[0-9\]{2}:\[0-9\]{2}:\[0-9\]{2}\\.\[0-9\]{3}Z$  |
| `error`  required  | `one of | null` |  Why the task failed when `status` is `failed`, else `null`.  one of: `TaskError`  |
| `id`  required  | `string` |  Task ID (a 53-bit integer as a string).  pattern: ^\[0-9\]+$  |
| `metadata`  optional  | `object` |  Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.  max 16 keys  |
| `metadata.<any key>`  optional  | `string` |  max length 256  |
| `params`  required  | `object | null` |  The task's parameters with secrets removed (proxy login and password, cookies where the type marks them sensitive) and strings longer than 256 bytes (images) replaced by `"[N bytes]"`. `null` when not available.  |
| `sandbox`  optional  | `const true` |  Present (true) on tasks created with a test key.  |
| `solution`  required  | `one of | null` |  The answer when `status` is `solved`, else `null`. Its shape depends on `type`.  one of: `Solution`  |
| `status`  required  | `enum` |  one of "processing", "solved", "failed"  |
| `type`  required  | `string` |  Canonical task type, e.g. `recaptcha.v2` (see `CreateTaskRequest`).  |

### 202

The task is still processing.

Headers: `Location` (optional), `Noptcha-Request-Id`, `Preference-Applied` (optional).

Content: `application/json`

| Field | Type | Description |
| --- | --- | --- |
| `completed_at`  optional  | `string` |  When the task became final; absent while processing.  format: date-time · pattern: ^\[0-9\]{4}-\[0-9\]{2}-\[0-9\]{2}T\[0-9\]{2}:\[0-9\]{2}:\[0-9\]{2}\\.\[0-9\]{3}Z$  |
| `cost`  required  | `object` |  What the task cost (zero unless solved and charged).  |
| `cost.amount`  required  | `string` |  Decimal US dollars with 6 places.  pattern: ^-?\[0-9\]+\\.\[0-9\]{6}$  |
| `cost.currency`  required  | `const "USD"` |  |
| `created_at`  required  | `string` |  format: date-time · pattern: ^\[0-9\]{4}-\[0-9\]{2}-\[0-9\]{2}T\[0-9\]{2}:\[0-9\]{2}:\[0-9\]{2}\\.\[0-9\]{3}Z$  |
| `error`  required  | `one of | null` |  Why the task failed when `status` is `failed`, else `null`.  one of: `TaskError`  |
| `id`  required  | `string` |  Task ID (a 53-bit integer as a string).  pattern: ^\[0-9\]+$  |
| `metadata`  optional  | `object` |  Your own key-value pairs, returned with the task. At most 16 keys; keys 1–64 characters, values strings of at most 256 characters (Unicode code points, as JSON Schema counts them). A value that is not a string is `422 invalid_params` with pointer `/metadata/<key>`.  max 16 keys  |
| `metadata.<any key>`  optional  | `string` |  max length 256  |
| `params`  required  | `object | null` |  The task's parameters with secrets removed (proxy login and password, cookies where the type marks them sensitive) and strings longer than 256 bytes (images) replaced by `"[N bytes]"`. `null` when not available.  |
| `sandbox`  optional  | `const true` |  Present (true) on tasks created with a test key.  |
| `solution`  required  | `one of | null` |  The answer when `status` is `solved`, else `null`. Its shape depends on `type`.  one of: `Solution`  |
| `status`  required  | `enum` |  one of "processing", "solved", "failed"  |
| `type`  required  | `string` |  Canonical task type, e.g. `recaptcha.v2` (see `CreateTaskRequest`).  |

### 401

`unauthorized`: the key is malformed, unknown, revoked or expired.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional).

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 403

`forbidden`: the key lacks the scope this endpoint needs, the client IP is not in the key's allowlist, the key may not use this task type, or the organization is suspended (`detail` says which). Also returned, without `detail`, when the request did not pass through our edge network.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional).

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 404

`not_found`: no such task, it expired (results are kept 10 minutes after completion) or it belongs to another organization; or the task created with this `Idempotency-Key` has expired.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional).

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 413

`request_too_large`: the body exceeds the limit (1 MB for image types, 64 KB otherwise). Any request with a body over 1 MB gets this, GET requests included.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional).

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 429

`rate_limited`: too many tasks created per second by this key, the same task polled too often, the sandbox's per-organization rate, usage queried too often, the catalog fetched too often from this IP, or this IP sent too many invalid keys. `concurrency_limited`: the organization has too many tasks in flight for this captcha family (or, with a test key, too many sandbox tasks still processing). Wait `Retry-After` seconds.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional), `Retry-After`.

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 500

`internal`: an error on our side.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional).

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

### 503

`service_unavailable`: no capacity right now (all solvers busy or failing, the gateway is overloaded, a dependency is unavailable). For `POST /v1/tasks` nothing was created or charged. Wait `Retry-After`.

Headers: `Noptcha-Request-Id`, `RateLimit` (optional), `RateLimit-Policy` (optional), `Retry-After`.

Content: `application/problem+json`

| Field | Type | Description |
| --- | --- | --- |
| `code`  required  | `string` |  Machine-readable error code (see the table).  |
| `detail`  optional  | `string` |  Human-readable explanation of this occurrence.  |
| `request_id`  required  | `string` |  Same as the `Noptcha-Request-Id` header.  |
| `status`  required  | `integer` |  The HTTP status code.  |
| `title`  required  | `string` |  |
| `type`  required  | `string` |  format: uri  |

Header descriptions and every schema: [Schemas](https://noptcha.com/docs/api-reference/schemas.md). Machine-readable: [openapi.json](https://noptcha.com/openapi.json), [openapi.yaml](https://noptcha.com/openapi.yaml).