> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavrn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 4. Track and download

> Follow a request with webhooks and incremental polling, answer action requests through the API, and download records and provider invoices with their amounts.

Tavrn works the request with the facility for days or weeks. Your integration needs three
things during that time: to know when something changed, to answer the occasional question,
and to pick up records and invoices when they land.

## Register a webhook

Create one endpoint for the three retrieval events. Needs `webhooks:write`.

```bash theme={null}
curl -X POST https://enterprise.tavrn.ai/v2/webhooks \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/tavrn/webhook",
    "events": [
      "retrieval_request.status_changed",
      "retrieval_request.action_required",
      "retrieval_request.documents_available"
    ]
  }'
```

| Event | When it fires |
| - | - |
| `retrieval_request.status_changed` | `status` or `stage` moved (submitted → contact found → request sent → acknowledged → … → completed) |
| `retrieval_request.action_required` | Tavrn needs something from your firm: invoice approval, a corrected authorization, a clarification |
| `retrieval_request.documents_available` | A record or provider invoice is ready to download |

Payloads are HMAC-signed; verify them with the secret returned at creation
([Signature verification](/guides/v2/webhooks#signature-verification)). Treat the payload as
a pointer: on every event, fetch the request and act on its current state.

```bash theme={null}
curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123 \
  -H "Authorization: Bearer $TAVRN_API_KEY"
```

`status` is one of `received`, `processing`, `action_required`, `completed`, `cancelled`;
`stage` is the finer step shown in Tavrn. Full tables in
[Track Status](/guides/v2/retrieval-guide#4-track-status).

## Reconcile with incremental polling

Webhooks can be missed; polling catches up. Keep a checkpoint and ask for everything that
changed since it:

```bash theme={null}
curl 'https://enterprise.tavrn.ai/v2/retrieval-requests?public_updated_since=2026-01-01T00%3A00%3A00.000Z&include=details&limit=100' \
  -H "Authorization: Bearer $TAVRN_API_KEY"
```

Upsert each result by `id`, follow `next` until it is `null`, then save
`next_public_updated_since` as the new checkpoint. The lower bound is inclusive, so compare
`public_updated_at` before overwriting a cached request. Details in
[Incremental polling](/guides/v2/retrieval-guide#incremental-polling).

## Answer action requests

When `status` is `action_required`, `pending_action_request` says what Tavrn needs. The most
common one is `payment_needed`: a provider invoice above your approval limit.

```bash theme={null}
curl -X POST https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/action-response \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Approved. Please pay the $85.00 invoice." }'
```

A clear approve or decline in `message` is enough for payments. Other reasons (a new
authorization, a corrected date of birth) take an attachment: upload it with the retrieval
`sign-upload` endpoint and pass the `upload_id`. See
[Responding to Action Requests](/guides/v2/retrieval-guide#responding-to-action-requests).

## Download records and invoices

On `documents_available` (or any time), list the request's documents:

```bash theme={null}
curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/documents \
  -H "Authorization: Bearer $TAVRN_API_KEY"
```

Each entry has a `category` of `records`, `invoice`, or `cost_summary`, with file metadata when available.
Invoice entries also carry `metadata.provider_fee_amount` in USD, so you can post the
provider fee to the matter before or after you download the PDF. Then fetch a time-limited
URL per document:

```bash theme={null}
curl https://enterprise.tavrn.ai/v2/retrieval-requests/rr_abc123/documents/rrdoc_001/download \
  -H "Authorization: Bearer $TAVRN_API_KEY"
```

Completed requests with finalized billing also include `cost_summary`, a PDF of
Tavrn credits and fees, provider fees, and the total. Use
`/documents/cost_summary/download` to get its download URL. See
[Request cost PDF](/guides/v2/retrieval-guide#request-cost-pdf).

`GET /v2/retrieval-requests/{id}` also returns `costs` (`provider_fees`, `tavrn_fee`,
`total_cost`, in USD; get endpoint only) and `documents_summary` counts, so one call is
enough to reconcile what a request has cost. The `documents_available` event lists the new
`document_ids` and `invoice_ids`. More in
[Download Records and Invoices](/guides/v2/retrieval-guide#5-download-records-and-invoices).

## Done

`completed` and `cancelled` are final. Keep polling after completion: a late provider invoice
can still arrive and shows up as a new document.

<CardGroup cols={2}>
  <Card title="Retrieval guide" icon="book" href="/guides/v2/retrieval-guide">
    Every field, status and edge case.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/guides/v2/webhooks">
    Payload shapes, signatures, retries.
  </Card>
</CardGroup>