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).
GET
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). 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:
{
"estimatedTotalPostCount": "32544",
"currentArchiveQuota": "50000",
"confirmationToken": "e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}GET
https://app.webz.io/confirmArchiveQuery?confirmationToken=CONFIRMATION_TOKEN
This charges your credits and queues the order. Response:
{
"confirmationToken": "e7044de3-e611-4e3c-9817-78e09e2cbb2e"
}GET
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:
{
"statusCode": "2",
"statusText": "Complete",
"downloadLink": "https://s3.amazonaws.com/xxxxxxxxx.zip"
}Poll getArchiveOrderStatus until statusCode is 2, then download the ZIP from downloadLink. The link is valid for 7 days - see Delivery.
| 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.