# Run in the background

By default a request waits for its screenshot. Add `async=true` to get an id right away and read the result later. Use it for long pages, for batches, or when your own request must answer fast.

## Start a screenshot

Send the same request as usual, with `async=true`. The answer is `202` with the screenshot in its first state.

**Start in the background**

```bash
curl -X POST "https://api.localscreenshot.com/v1/screenshot" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.wikipedia.org",
    "full_page": true,
    "async": true
  }'
```

**202**

```http
HTTP/1.1 202 Accepted
Location: https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR
Retry-After: 2
```

**The body**

```json
{
  "id": "01JABCDEF2G3H4J5K6M7N8P9QR",
  "status": "queued",
  "image": null,
  "page": null,
  "credits": { "charged": null, "reserved": 1, "remaining": 49 },
  "error": null,
  "links": { "self": "https://api.localscreenshot.com/v1/screenshots/01JABC..." }
}
```

## Read the result

Read the address given in `Location` until `status` is `succeeded` or `failed`. Wait the number of seconds in `Retry-After` between two reads.

**Read it**

```bash
curl "https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY"
```

| Status | What it means |
| --- | --- |
| `queued` | Waiting for a free browser. |
| `running` | The page is being loaded. |
| `succeeded` | Done. `image` holds the link. |
| `failed` | Done, without an image. `error` says why. |

Reading a screenshot answers `200` whatever its status: look at `status` and `error`, not at the HTTP code.

## When a normal request also answers 202

A request without `async` waits up to 50 seconds. If the screenshot is not finished by then, the answer is the same `202`, with the same `Location`. The work is not lost: read it the same way.

## Credits

- The credits are reserved when the screenshot starts, and charged when it succeeds. A failed screenshot is not charged.
- `credits.charged` is `null` while the screenshot is running, then says what it cost.
- Screenshots in the background count toward the number you can run at once. See [Credits and limits](https://docs.localscreenshot.com/credits).

> **No webhooks yet.** We do not call your server when a screenshot is done. Read the screenshot until it is finished.