# Archive API

The Archive API builds and delivers a dataset in **three steps**: set the query, confirm the order, then poll for the download link.

All requests need your API `token`, and orders are paid with **prepaid credits**. Errors always return JSON with `errorText` and `errorCode` (see the table at the end).

## 1. Set query and time frame

`GET`

```bash
https://app.webz.io/setArchiveQuery?token=YOUR_TOKEN&q=(ipod OR ipad) -android&sm=05&sy=2021&em=09&ey=2022
```

| Parameter | Description |
| --- | --- |
| `token` | Your API token. |
| `q` | Boolean query (see [Building Queries](archive-query-filters)). Cannot be empty. |
| `sm` | Start month, `01`-`12`. Earliest start is 5 years back. |
| `sy` | Start year. |
| `em` | End month, `01`-`12` (inclusive). Cannot be a future month. |
| `ey` | End year (inclusive). |
| `format` | Optional. `ndjson` is the only value the API accepts - `json` and `xml` are rejected. |

The API runs your query against the **last 30 days** of live data to estimate volume, checks your credit balance, and reserves a pending order. Nothing runs or gets charged until you confirm.

Response:

```json
{
  "estimatedTotalPostCount": "32544",
  "currentArchiveQuota": "50000",
  "confirmationToken": "e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}
```

## 2. Confirm the order

`GET`

```bash
https://app.webz.io/confirmArchiveQuery?confirmationToken=CONFIRMATION_TOKEN
```

This charges your credits and queues the order. Response:

```json
{
  "confirmationToken": "e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}
```

## 3. Check status and download

`GET`

```bash
https://app.webz.io/getArchiveOrderStatus?confirmationToken=CONFIRMATION_TOKEN
```

| Field | Meaning |
| --- | --- |
| `statusCode` | `0` queued, `1` retrieving data, `2` complete. |
| `statusText` | `Queued`, `Retrieving Data`, or `Complete`. |
| `downloadLink` | ZIP download link. Empty until `statusCode` is `2`. |

Response when complete:

```json
{
  "statusCode": "2",
  "statusText": "Complete",
  "downloadLink": "https://s3.amazonaws.com/xxxxxxxxx.zip"
}
```

> [!TIP]
> Poll `getArchiveOrderStatus` until `statusCode` is `2`, then download the ZIP from `downloadLink`. The link is valid for 7 days - see [Delivery](archive-delivery).

## Error codes

| Code | Endpoint | Meaning |
| --- | --- | --- |
| `1` | set | Query matches fewer than 10 posts in the last 30 days. |
| `2` | set | Error running the query. |
| `3` | set | Empty query. |
| `4` | set | Start date is earlier than 5 years back. |
| `5` | set | End date is in the future. |
| `6` / `15` | set | Start date is after end date. |
| `7` | set | `performance_score` filter used before May 2015. |
| `8` | set | Sentiment filter used before June 2016. |
| `9` | set | Unknown API token. |
| `10` | set / confirm | Not enough credits for the estimated post count. |
| `11` | confirm | A previous order is still pending; wait for it to finish. |
| `21` | confirm | Unknown confirmation token. |
| `30` / `31` | status | Missing / unknown confirmation token. |
| `33` | set | Format other than `ndjson` requested. |

For what's inside the ZIP, see [Output Format](archive-output-format).