API Reference

SightRadar Face Recognition API

An AWS-Rekognition-compatible REST API for face indexing and search, where you only pay for what you use — billed per photo. New here? Start with the quickstart — provision a key, index a face, run a search, and check your wallet in four calls.

Quickstart Download OpenAPI spec View OpenAPI spec

Official SDKs: Python SDK Node / TypeScript SDK

Endpoint reference

All 32 endpoints of the SightRadar Face Recognition API, version 1.0.0. Base URL https://api.sightradar.com. Authenticate with Authorization: Bearer frs_<prefix>_<secret> — see the quickstart to get a key. The interactive playground for these same endpoints is below.

Collections

Create and manage face collections (the registry of your indexed photos).

GET/v1/collections

List collections

Lists your collections, newest first, paged via limit/offset. Pass `q` to filter by a case-insensitive substring of the collection ID. Returns the matching `total` so clients can paginate accurately. Free.

GET https://api.sightradar.com/v1/collections

Parameters

Field	Type	Description
`limit`in query	`integer`	—
`offset`in query	`integer`	—
`q`in query	`string`	Case-insensitive LITERAL substring filter on collection_id (max 100 chars; wildcard characters are matched literally).

Response body

Field	Type	Description
`collections`	`object[]`	—
`total`	`integer`	Total collections matching the filter (ignores limit/offset).
`limit`	`integer`	—
`offset`	`integer`	—

Status codes

200 Your collections.
401 Missing or invalid API key.

POST/v1/collections

Create a collection

Creates a new face collection owned by your account. Free (0 credits).

POST https://api.sightradar.com/v1/collections

Request body (application/json)

Field	Type	Description
`collection_id`required	`string`	Your chosen identifier for the collection.

Response body

Field	Type	Description
`collection_id`	`string`	—
`status`	`"active" \| "deleting" \| "deleted"`	—
`photo_count`	`integer`	—
`face_count`	`integer`	—
`selfie_count`	`integer`	—
`created_at`	`string`	—

Status codes

200 Collection created.
400 collection_id missing.
401 Missing or invalid API key.
409 Collection already exists in a non-active state.

GET/v1/collections/{id}

Describe a collection

Returns the collection with LIVE face/selfie counts merged from the engine. Free.

GET https://api.sightradar.com/v1/collections/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.

Response body

Field	Type	Description
`collection_id`	`string`	—
`status`	`"active" \| "deleting" \| "deleted"`	—
`photo_count`	`integer`	—
`face_count`	`integer`	—
`selfie_count`	`integer`	—
`created_at`	`string`	—

Status codes

200 Collection detail.
401 Missing or invalid API key.
404 Resource not found.

DELETE/v1/collections/{id}

Delete a collection (soft by default, restorable)

Schedules a durable cascade delete — all faces and selfies are removed asynchronously. Returns 202 with a workflow id. Free.

Two modes:

* **Soft (default, no flag)** — the collection is tagged `deletion_pending` and stops accepting index/search operations *immediately*, but nothing is erased until the grace window elapses. Undo with `POST /v1/collections/{id}/restore` any time before the purge starts. This is the safe default: an accidental mass-delete from your own automation is recoverable. * **Immediate (`?immediate=true`)** — skips the grace window and starts erasing now. NOT restorable.

`?compliance=true` is an alias for `immediate=true` that additionally records the erasure as compliance-class for your own audit trail.

Poll `GET /v1/collections/{id}/deletion` for authoritative progress.

DELETE https://api.sightradar.com/v1/collections/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.
`immediate`in query	`boolean`	Skip the grace window and begin erasing now. Not restorable.
`compliance`in query	`boolean`	Alias for `immediate=true`, additionally recorded as a compliance-class erasure.

Response body

Field	Type	Description
`status`	`"deletion_pending" \| "deleting"`	`deletion_pending` for a soft delete (still restorable); `deleting` once erasure has been scheduled.
`mode`	`"soft" \| "immediate"`	—
`workflow_id`	`string`	—
`restorable`	`boolean`	True for a soft delete (undo via `POST /v1/collections/{id}/restore`); false for an immediate delete.
`purge_after`	`string`	When the grace window elapses and erasure begins. Soft deletes only.
`message`	`string`	—

Status codes

202 Deletion scheduled.
401 Missing or invalid API key.
404 Resource not found.
409 Collection is already deleting or deleted.

POST/v1/collections/{id}/restore

Undo a soft collection delete

Restores a collection that is still inside its grace window (`status=deletion_pending`) back to `active`, cancelling the scheduled purge. The collection keeps the same incarnation, and any batch work that was paused by the delete resumes. Free and idempotent.

Returns 409 once the purge has actually started (`status=deleting`) — vectors are being erased at that point, so a restore could not honestly return the collection intact. Also 409 for a compliance-class erasure, which is deliberately not restorable.

POST https://api.sightradar.com/v1/collections/{id}/restore

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.

Response body

Field	Type	Description
`status`	`string`	—
`message`	`string`	—

Status codes

200 Collection restored.
401 Missing or invalid API key.
403 Account is read-only.
404 Resource not found.
409 Not restorable — the purge has already started, or this was a compliance-class erasure.

POST/v1/collections/{id}/photos/{photoId}/restore

Undo a soft photo delete

Un-deletes a soft-deleted photo's faces so they are searchable again. Only works while the vectors still exist — i.e. for a soft delete inside its grace window. An immediate delete physically removed the vectors and cannot be undone; re-index the photo instead. Free and idempotent.

POST https://api.sightradar.com/v1/collections/{id}/photos/{photoId}/restore

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.
`photoId`requiredin path	`string`	The photoId supplied at index time.

Response body

Field	Type	Description
`restored`	`boolean`	—
`collection_id`	`string`	—
`photo_id`	`string`	—

Status codes

200 Faceprints restored.
401 Missing or invalid API key.
403 Account is read-only.
404 Resource not found.
502 Deletion service unavailable.

GET/v1/collections/{id}/deletion

Get collection deletion status

Authoritative status for an asynchronous collection deletion. Poll until `phase=completed` and `verified_zero=true` before removing a client-side tombstone. Active collections return `phase=not_deleting`. Free.

GET https://api.sightradar.com/v1/collections/{id}/deletion

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.

Response body

Field	Type	Description
`collection_id`required	`string`	—
`phase`required	`"not_deleting" \| "deletion_pending" \| "deleting" \| "completed" \| "blocked"`	—
`collection_status`required	`"active" \| "deletion_pending" \| "deleting" \| "deleted"`	—
`verified_zero`required	`boolean`	—
`attempts`required	`integer`	—
`deletion_class`	`"product" \| "compliance"`	—
`workflow_id`	`string`	—
`workflow_status`	`"pending" \| "completed" \| "failed"`	—
`purge_after`	`string`	—
`requested_at`	`string`	—
`completed_at`	`string`	—
`last_error`	`string`	—

Status codes

200 Current deletion lifecycle.
401 Missing or invalid API key.
404 Resource not found.

GET/v1/collections/{id}/metrics

Collection metrics

Live face/selfie counts straight from the engine's vector store. Free.

GET https://api.sightradar.com/v1/collections/{id}/metrics

Parameters

Field	Type	Description
`id`requiredin path	`string`	—

Response body

Field	Type	Description
`collection_id`	`string`	—
`status`	`string`	—
`photo_count`	`integer`	—
`face_count`	`integer`	—
`selfie_count`	`integer`	—

Status codes

200 Counts.
401 Missing or invalid API key.
404 Resource not found.
502 Engine metrics unavailable.

DELETE/v1/collections/{id}/photos/{photoId}

Delete one photo's faceprints (soft by default, restorable)

Deletes the face vectors indexed from one photo (by the `photoId` you supplied at index time), without touching the rest of the collection. Synchronous and free. Idempotent — deleting an already-removed photo still returns 200.

Two modes, mirroring the collection delete:

* **Soft (default, no flag)** — the faces are tagged deleted and drop out of search *immediately*, but the vectors survive the grace window so the delete can be undone with `POST /v1/collections/{id}/photos/{photoId}/restore`. This is the safe default: an accidental delete from your own automation is recoverable. * **Immediate (`?immediate=true`)** — the vectors are physically removed now. NOT restorable.

`?compliance=true` is an alias for `immediate=true` that additionally records the erasure as compliance-class for your own audit trail.

DELETE https://api.sightradar.com/v1/collections/{id}/photos/{photoId}

Parameters

Field	Type	Description
`id`requiredin path	`string`	Collection id.
`photoId`requiredin path	`string`	The photoId supplied at index time.
`immediate`in query	`boolean`	Physically delete the vectors now instead of soft-deleting them. Not restorable.
`compliance`in query	`boolean`	Alias for `immediate=true`, additionally recorded as a compliance-class erasure.

Response body

Field	Type	Description
`deleted`	`boolean`	—
`collection_id`	`string`	—
`photo_id`	`string`	—
`mode`	`"soft" \| "immediate"`	Which delete mode was applied.
`restorable`	`boolean`	True for a soft delete (undo via the restore endpoint); false for an immediate delete.

Status codes

200 Faceprints deleted.
401 Missing or invalid API key.
404 Resource not found.
502 Deletion service unavailable.

Faces

Index, search, detect, and compare faces (billable operations).

POST/v1/collections/{id}/index

Index faces from a photo

Detects all quality-gated faces in an image and stores them in the collection (Rekognition `IndexFaces`). **Billable: 93 credits (real-time tier).**

Provide the image as JSON `{url}` / `{gcsKey}`, a multipart `file`, or raw image bytes. Optional `photoId` is the per-image key (defaults to a content hash).

POST https://api.sightradar.com/v1/collections/{id}/index

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`photoId`in query	`string`	Per-image key (also accepted in body).
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409.

Request body (application/json)

Field	Type	Description
`url`	`string`	Public image URL.
`gcsKey`	`string`	Google Cloud Storage object key.
`photoId`	`string`	Optional per-image key.

Also accepts: multipart/form-data, application/octet-stream

Response body

Field	Type	Description
`collection_id`	`string`	—
`photo_id`	`string`	—
`indexed`	`integer`	Faces stored.
`detected_face_count`	`integer`	—
`rejected_face_count`	`integer`	Detected but quality-gated out.
`faces`	`object[]`	—
`model_version`	`string`	—

Status codes

200 Faces indexed.
400 Cannot decode image, or no url/gcsKey/body provided.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
409 A request with this Idempotency-Key is in flight or already processed.
413 Image exceeds the 30 MB encoded size cap.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/collections/{id}/search

Search a collection

Search by a selfie image OR a precomputed 512-d embedding. Returns the matching photo ids ranked by similarity. **Billable: 93 credits (real-time tier).**

POST https://api.sightradar.com/v1/collections/{id}/search

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409.

Request body (application/json)

Field	Type	Description
`embedding`	`number[]`	—
`url`	`string`	—
`gcsKey`	`string`	—
`threshold`	`number`	Min cosine similarity (0-1).
`limit`	`integer`	Max matches.

Also accepts: multipart/form-data

Response body

Field	Type	Description
`collection_id`	`string`	—
`matches`	`object[]`	—
`photo_ids`	`string[]`	—
`reason`	`string`	Present when no match: no_face \| low_quality_selfie \| point_not_found.
`model_version`	`string`	—

Status codes

200 Search result.
400 Cannot decode image, or no url/gcsKey/body provided.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
409 A request with this Idempotency-Key is in flight or already processed.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/collections/{id}/search-by-id

Search by a stored selfie point id

Search using a previously-registered selfie's `pointId` (Rekognition `SearchFaces` by FaceId). **Billable: 62 credits (search-by-face-id tier).**

POST https://api.sightradar.com/v1/collections/{id}/search-by-id

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409.

Request body (application/json)

Field	Type	Description
`pointId`required	`string`	A point_id returned by /selfies.
`threshold`	`number`	Min cosine similarity (0-1).
`limit`	`integer`	Max matches to return.

Response body

Field	Type	Description
`collection_id`	`string`	—
`matches`	`object[]`	—
`photo_ids`	`string[]`	—
`reason`	`string`	Present when no match: no_face \| low_quality_selfie \| point_not_found.
`model_version`	`string`	—

Status codes

200 Search result.
400 pointId missing.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/detect

Detect faces (no storage)

Detect + quality-gate faces in an image WITHOUT storing anything (Rekognition `DetectFaces`). **Billable: 93 credits (real-time tier).**

POST https://api.sightradar.com/v1/detect

Parameters

Field	Type	Description
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409.

Request body (application/json)

Field	Type	Description
`url`	`string`	Public image URL.
`gcsKey`	`string`	Google Cloud Storage object key.
`photoId`	`string`	Optional per-image key.

Also accepts: multipart/form-data, application/octet-stream

Response body

Field	Type	Description
`detected_face_count`	`integer`	—
`gated_face_count`	`integer`	—
`faces`	`object[]`	—

Status codes

200 Detection result.
400 Cannot decode image, or no url/gcsKey/body provided.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

POST/v1/compare

Compare two faces

Compare the best face in two images (Rekognition `CompareFaces`). Returns cosine similarity (0-1) and a match boolean at the configured threshold.

**Billable: 93 credits per image processed (real-time tier).** This is the ONLY endpoint that can process two photos in one request, and billing is per photo processed: - two images (source + target) → **186 credits** - one image + one precomputed embedding → **93 credits** - two precomputed embeddings → **93 credits** (one billable operation; no image is fetched or run through the model) A side supplied as `source_embedding` / `target_embedding` is not a processed photo and is not charged as one.

POST https://api.sightradar.com/v1/compare

Parameters

Field	Type	Description
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409.

Request body (application/json)

Field	Type	Description
`sourceUrl`	`string`	—
`sourceGcsKey`	`string`	—
`targetUrl`	`string`	—
`targetGcsKey`	`string`	—
`source_embedding`	`number[]`	—
`target_embedding`	`number[]`	—

Response body

Field	Type	Description
`face_found`	`boolean`	—
`similarity`	`number,null`	Cosine similarity (0-1).
`match`	`boolean`	—
`threshold`	`number`	—

Status codes

200 Comparison result.
400 Bad body or missing source/target.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

Selfies

POST/v1/collections/{id}/selfies

Register a selfie

Register a single-face selfie (Rekognition `IndexFaces` MaxFaces=1). Returns a `point_id` you can later pass to `search-by-id`. **Billable: 93 credits (real-time tier).**

POST https://api.sightradar.com/v1/collections/{id}/selfies

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`userId`in query	`string`	Required (also accepted in body).
`selfieId`in query	`string`	Optional; defaults to a content hash.
`Idempotency-Key`in header	`string`	Opt-in idempotency. A replay under the same key is never re-charged. For a selfie register it returns 200 with the stored result (Idempotent-Replay: true) when the registration identity matches; every other op returns 409.

Request body (application/json)

Field	Type	Description
`url`	`string`	Public image URL.
`gcsKey`	`string`	Google Cloud Storage object key.
`photoId`	`string`	Optional per-image key.
`userId`required	`string`	—
`selfieId`	`string`	—

Also accepts: multipart/form-data

Status codes

200 Selfie processed (check face_found). On a settled idempotent replay of the SAME registration (same collection + userId + selfieId), the body is the reduced SelfieReplayResult and the Idempotent-Replay header is true.
400 userId missing or bad image.
401 Missing or invalid API key.
402 Wallet balance too low for this operation.
429 Per-key RPS or per-customer concurrency limit exceeded.
502 Engine error (the credit hold is refunded automatically).

Batch

Asynchronous bulk processing with webhook callbacks.

GET/v1/batches

List batches

List your most recent batches (newest first) with per-status job counts. Use this to power a dashboard history view. Free.

GET https://api.sightradar.com/v1/batches

Parameters

Field	Type	Description
`limit`in query	`integer`	—

Response body

Field	Type	Description
`batches`	`object[]`	—

Status codes

200 Recent batches.
401 Missing or invalid API key.

POST/v1/batches

Submit a batch job

Fire-and-forget bulk processing of up to 1000 **URL-only** photos. base64 is rejected in batch — use real-time endpoints for inline images. Results arrive per-photo via your registered webhook, or poll `GET /v1/batches/{id}`.

POST https://api.sightradar.com/v1/batches

Request body (application/json)

Field	Type	Description
`collection_id`required	`string`	—
`op`required	`"index" \| "match"`	—
`webhook_endpoint_id`	`string`	Optional; an endpoint id from POST /v1/webhooks.
`photos`required	`object[]`	—

Response body

Field	Type	Description
`batch_id`	`string`	—
`total_photos`	`integer`	—
`status`	`string`	—
`message`	`string`	—

Status codes

202 Batch accepted.
400 Validation error (missing fields, base64 in batch, too large).
401 Missing or invalid API key.

POST/v1/batches/failed/requeue

Preview or execute a failed-photo retry wave

Safely retries one bounded wave of eligible, uncharged terminal batch photos for the authenticated customer. Only `insufficient_credits`, `internal_error`, and `retry_exhausted` are retryable. Charged photos, photos with a live reservation, and photos already covered or in flight in another batch are excluded.

First send scope fields with `execute` omitted or false. The response is a ten-minute, one-time preview. Then send only its `preview_id` with `execute: true`. Execute uses the stored server-side scope and may requeue fewer photos when eligibility changed after preview.

Preview never reserves or debits credits. `balance_credits` and `has_estimated_balance` are advisory snapshots. Workers reserve the normal per-photo batch price when each retried photo is processed.

POST https://api.sightradar.com/v1/batches/failed/requeue

Status codes

200 Preview created or one-time retry executed.
400 Malformed JSON, non-retryable reason, invalid bounds/date range, or invalid request mode.
401 Missing or invalid API key.
403 Read-only tenant-alias accounts cannot preview or execute retries.
404 Preview missing or owned by another customer.
409 Preview expired or was already consumed (`preview_expired` or `preview_consumed`).
500 Preview store or wallet lookup failed.

POST/v1/batches/statuses

Get statuses for an explicit batch set

Returns progress aggregates for up to 5,000 requested batch IDs in one tenant-scoped query. Missing or foreign-tenant IDs are omitted. Intended for polling exact historical parent batches reopened by a retry wave.

POST https://api.sightradar.com/v1/batches/statuses

Request body (application/json)

Field	Type	Description
`batch_ids`required	`string[]`	—

Response body

Field	Type	Description
`batches`required	`object[]`	—

Status codes

200 Owned requested batches, preserving first-requested order.
400 Invalid JSON, empty/oversized ID list, or malformed UUID.
401 Missing or invalid API key.

GET/v1/batches/{id}

Get batch status

Poll a batch's progress (webhook-down fallback). Free.

GET https://api.sightradar.com/v1/batches/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	—

Response body

Field	Type	Description
`batch_id`	`string`	—
`collection_id`	`string`	—
`op`	`string`	—
`status`	`string`	—
`total_photos`	`integer`	—
`succeeded`	`integer`	—
`failed`	`integer`	—
`pending`	`integer`	—
`claimed`	`integer`	—
`created_at`	`string`	—

Status codes

200 Batch status.
401 Missing or invalid API key.
404 Resource not found.

GET/v1/batches/{id}/photos

Get per-photo batch results

Authoritative pull fallback for every photo in a batch. Results are keyset-paginated by zero-based `photo_index`; use `next_after_index` while `has_more=true`. Free.

GET https://api.sightradar.com/v1/batches/{id}/photos

Parameters

Field	Type	Description
`id`requiredin path	`string`	—
`limit`in query	`integer`	—
`after_index`in query	`integer`	—

Response body

Field	Type	Description
`batch_id`	`string`	—
`collection_id`	`string`	—
`status`	`string`	—
`total_photos`	`integer`	—
`photos`	`object[]`	—
`has_more`	`boolean`	—
`next_after_index`	`integer`	—

Status codes

200 Per-photo batch outcomes.
401 Missing or invalid API key.
404 Resource not found.

Webhooks

GET/v1/webhooks

List webhook endpoints

GET https://api.sightradar.com/v1/webhooks

Parameters

Field	Type	Description
`status`in query	`"active" \| "inactive"`	Filter endpoints by lifecycle. Omit for all endpoints.

Response body

Field	Type	Description
`webhooks`	`object[]`	—

Status codes

200 Your webhook endpoints.
401 Missing or invalid API key.

POST/v1/webhooks

Register a webhook endpoint

Register an HTTPS URL to receive per-photo batch results and verified collection-deletion completion events. We sign every delivery with HMAC-SHA256 over `timestamp.body`. If you omit `secret`, one is generated and returned **once**. Callback bodies are either BatchWebhookEvent or DeletionWebhookEvent.

POST https://api.sightradar.com/v1/webhooks

Request body (application/json)

Field	Type	Description
`url`required	`string`	Public HTTPS URL.
`secret`	`string`	Optional signing secret; generated if omitted.

Response body

Field	Type	Description
`webhook_endpoint_id`	`string`	—
`url`	`string`	—
`status`	`string`	—
`secret`	`string`	Returned ONCE only when generated.
`note`	`string`	—

Status codes

200 Endpoint registered.
400 Invalid or non-HTTPS/private URL.
401 Missing or invalid API key.
503 Webhook encryption key not configured.

DELETE/v1/webhooks/{id}

Disable a webhook endpoint

Stops new and queued deliveries for this endpoint. Historical delivery records remain available for audit and batch results remain pollable. Repeating the request is idempotent for the endpoint owner.

DELETE https://api.sightradar.com/v1/webhooks/{id}

Parameters

Field	Type	Description
`id`requiredin path	`string`	—

Response body

Field	Type	Description
`webhook_endpoint_id`	`string`	—
`status`	`"disabled"`	—

Status codes

200 Endpoint disabled.
401 Missing or invalid API key.
403 Read-only accounts cannot disable endpoints.
404 Resource not found.

GET/v1/webhooks/dead-letters

List dead-lettered webhook deliveries

Lists delivery metadata after the retry budget is exhausted. Payloads and signing secrets are never returned.

GET https://api.sightradar.com/v1/webhooks/dead-letters

Parameters

Field	Type	Description
`limit`in query	`integer`	—

Response body

Field	Type	Description
`dead_letters`	`object[]`	—

Status codes

200 Dead-lettered deliveries owned by the caller.
401 Missing or invalid API key.

POST/v1/webhooks/dead-letters/replay

Replay dead-lettered webhook deliveries

Requeues selected deliveries, or every eligible delivery when the body is absent. Stable idempotency keys are preserved.

POST https://api.sightradar.com/v1/webhooks/dead-letters/replay

Request body (application/json)

Field	Type	Description
`delivery_ids`	`string[]`	—

Response body

Field	Type	Description
`requeued`	`integer`	—

Status codes

200 Replay accepted.
400 Invalid JSON body.
401 Missing or invalid API key.
403 Read-only accounts cannot replay deliveries.

Wallet & Usage

Check your credit balance, usage, and auto-recharge config.

GET/v1/wallet

Get credit balance

Returns your current prepaid credit balance. Free.

GET https://api.sightradar.com/v1/wallet

Response body

Field	Type	Description
`balance_credits`	`integer`	—

Status codes

200 Balance.
401 Missing or invalid API key.

GET/v1/usage

Usage report

Per-operation usage aggregation over the last N days (default 30, max 365). Free.

GET https://api.sightradar.com/v1/usage

Parameters

Field	Type	Description
`days`in query	`integer`	—

Response body

Field	Type	Description
`days`	`integer`	—
`by_op`	`object[]`	—
`total_calls`	`integer`	—
`total_credits`	`integer`	—

Status codes

200 Usage breakdown.
401 Missing or invalid API key.

GET/v1/usage/daily

Daily usage time series

Daily spend time series for charting: each operation individually, a combined operations line, and the daily face-vector storage charge — all index-aligned to one dense UTC `dates` axis, so no client-side date alignment or gap filling is needed.

Window semantics match `GET /v1/usage`: a custom `from`/`to` range wins when both parse, otherwise `days` (default 30, max 365). Days with no activity are present in the axis with `0` values.

Operations and storage are kept as SEPARATE series because they are different cost models (per-call vs per-day off stored vector count). `total_credits` is the per-day grand total (`ops_total_credits` + `storage.credits_owed`); it uses storage OWED, not debited, so the total reflects true cost even during a wallet shortfall or shadow mode.

Free (0-credit) control-plane operation.

GET https://api.sightradar.com/v1/usage/daily

Parameters

Field	Type	Description
`days`in query	`integer`	—
`from`in query	`string`	Window start, inclusive (YYYY-MM-DD or RFC3339). Requires `to`.
`to`in query	`string`	Window end, exclusive (YYYY-MM-DD or RFC3339); a bare date includes that whole day. Requires `from`.

Response body

Field	Type	Description
`days`	`integer`	—
`from`	`string`	Resolved window start (inclusive).
`to`	`string`	Resolved window end (exclusive).
`dates`	`string[]`	Dense UTC day axis, oldest first. All series below are index-aligned to it.
`ops`	`object[]`	Per-operation daily series, ordered by window spend descending.
`ops_total_credits`	`integer[]`	Combined per-day operations cost (Σ over ops). Excludes storage.
`ops_total_calls`	`integer[]`	—
`storage`	`object`	Daily face-vector storage cost on the same date axis.
`total_credits`	`integer[]`	Per-day grand total = ops_total_credits + storage.credits_owed.

Status codes

200 Daily series. Every array is the same length as `dates`.
401 Missing or invalid API key.

Health

Liveness and readiness probes (unauthenticated).

GET/healthno auth

Liveness probe (alias of /healthz)

Process is up and serving. No dependencies. Unauthenticated. Conventional alias of /healthz for uptime monitors.

GET https://api.sightradar.com/health

Response body

Field	Type	Description
`status`	`string`	—

Status codes

200 Service is alive.

GET/healthzno auth

Liveness probe

Process is up and serving. No dependencies. Unauthenticated.

GET https://api.sightradar.com/healthz

Response body

Field	Type	Description
`status`	`string`	—

Status codes

200 Service is alive.

GET/readyzno auth

Readiness probe

Verifies the Postgres connection. 200 = ready, 503 = not ready. Unauthenticated.

GET https://api.sightradar.com/readyz

Response body

Field	Type	Description
`status`	`string`	—
`postgres`	`string`	—

Status codes

200 Ready to serve traffic.
503 Not ready (Postgres down or unconfigured).

Interactive playground

Try any endpoint against the live API with your own key.