# Exports

PDF reports and Excel workbooks of a crawl, generated asynchronously.

## Request a crawl export

`POST /v1/crawls/{crawl}/exports`

Queues the PDF report or the Excel workbook of a finished crawl and answers
`202` with the export to poll (`Location`). Excel requires a plan that
includes it (`plan_limit.exports.excel`). An identical export still in
progress is returned instead of starting a second one.


- Required scopes: `exports:write`
- Rate-limit cost: 10 unit(s)
- Idempotency-Key accepted

### Parameters

- `crawl` (path, string (uuid), required)

### Request body

- `format` (string, required) [pdf, xlsx]

### Responses

- `202`: OK.
- `400`: Malformed request, such as an invalid pagination cursor (`pagination.invalid_cursor`).
- `401`: Missing, invalid or expired token, or a member who left the team.
- `403`: The plan does not include the API (`api.not_in_plan`) or this verb
(`api.write_not_in_plan`), or the token lacks a scope
(`token.missing_scope`).

- `404`: No such resource for the token's team. Resources of another team answer 404 as well, never 403.
- `409`: The request conflicts with the current state (a crawl already running, an idempotency key in use, a project not ready).
- `422`: Invalid query or body values (`validation_failed`), with `errors` by field.
- `429`: The plan rate limit is exhausted for one window.

### Request example (cURL)

```bash
curl -X POST "https://api.nessflow.com/v1/crawls/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/exports" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"format":"pdf"}'
```

### Response example

```json
{
    "data": {
        "id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "crawl_id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "format": "pdf",
        "status": "queued",
        "size_bytes": 42,
        "download_url": "https://exemple.fr/",
        "created_at": "2026-10-01T09:30:00Z",
        "finished_at": "2026-10-01T09:30:00Z",
        "expires_at": "2026-10-01T09:30:00Z"
    }
}
```

## Get an export

`GET /v1/exports/{export}`

Status of an export. When `status` is `ready`, `download_url` is set until `expires_at`.


- Required scopes: `crawls:read`
- Rate-limit cost: 1 unit(s)

### Parameters

- `export` (path, string (uuid), required)

### Responses

- `200`: OK.
- `401`: Missing, invalid or expired token, or a member who left the team.
- `403`: The plan does not include the API (`api.not_in_plan`) or this verb
(`api.write_not_in_plan`), or the token lacks a scope
(`token.missing_scope`).

- `404`: No such resource for the token's team. Resources of another team answer 404 as well, never 403.
- `429`: The plan rate limit is exhausted for one window.

### Request example (cURL)

```bash
curl "https://api.nessflow.com/v1/exports/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

### Response example

```json
{
    "data": {
        "id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "crawl_id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "format": "pdf",
        "status": "queued",
        "size_bytes": 42,
        "download_url": "https://exemple.fr/",
        "created_at": "2026-10-01T09:30:00Z",
        "finished_at": "2026-10-01T09:30:00Z",
        "expires_at": "2026-10-01T09:30:00Z"
    }
}
```

## Download an export

`GET /v1/exports/{export}/download`

The file, as an attachment. `409 export.not_ready` while it is being generated, `410 export.expired` once removed.


- Required scopes: `crawls:read`
- Rate-limit cost: 1 unit(s)

### Parameters

- `export` (path, string (uuid), required)

### Responses

- `200`: OK.
- `401`: Missing, invalid or expired token, or a member who left the team.
- `403`: The plan does not include the API (`api.not_in_plan`) or this verb
(`api.write_not_in_plan`), or the token lacks a scope
(`token.missing_scope`).

- `404`: No such resource for the token's team. Resources of another team answer 404 as well, never 403.
- `409`: The request conflicts with the current state (a crawl already running, an idempotency key in use, a project not ready).
- `410`: The resource existed and has been removed (`export.expired`).
- `429`: The plan rate limit is exhausted for one window.

### Request example (cURL)

```bash
curl "https://api.nessflow.com/v1/exports/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/download" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```