# Requests, results and retries

Every processing endpoint starts a **request** that runs in the background. The response is the request itself, with status `queued`.

## Statuses

| Status | Meaning |
| --- | --- |
| `queued` | Accepted, waiting for a worker. |
| `processing` | Running. Video requests report `progress` (0–100). |
| `succeeded` | Finished. `result` holds the data and the files. |
| `failed` | Finished without a result. `error` says why. Not charged. |
| `aborted` | Stopped with `POST /v1/requests/{id}/abort`. Not charged. |

Poll `GET /v1/requests/{id}` every few seconds (images take about a second; videos take longer), or pass `webhook_url` to be told (see [Webhooks](https://api.watermark.ws/docs/webhooks.md)).

## Results

`result.files[].url` is a download link that works until the file is deleted, 7 days after the request finishes (`url_expires_at`, the same moment as `result.deleted_at`). Anyone with the link can download the file, so share it only where the file may go. Opening it redirects to the file itself. `result.data` describes the output: dimensions and format for images, duration and codec for videos, pages and size for PDFs.

Read endpoints (`images/read`, `videos/read`, `documents/read`) return `result.data` only.

## Sources

`source` must be a public `http` or `https` URL on the default port. The API refuses private, loopback and cloud-metadata addresses, follows at most 3 redirects, and only processes these formats:

- Images: JPEG, PNG, GIF, WebP, TIFF, BMP, HEIC, AVIF
- Videos: MP4, MOV, WebM, MKV, AVI, FLV, MPEG, MPEG-TS
- Documents: PDF

## Idempotency

Send an `Idempotency-Key` header (any unique string up to 255 characters) to make a retry safe. The same key with the same body returns the first request (`200`, header `Idempotent-Replayed: true`) instead of starting and charging a second one. The same key with a different body is a `409`.

## Your own references

`customer` (up to 64 characters) and `metadata` (up to 20 keys of text) are stored on the request, returned with it and sent in its webhooks. Use them to tie requests to your own users and orders; [`GET /v1/usage?group_by=customer`](https://api.watermark.ws/docs/reference.md#get-usage) totals them.