List, inspect, then query — any dataset
01
List & pick a dataset
GET /v1/datasets (free) returns every dataset with its id, name and record count. Use that id in the other endpoints.02
Read the schema
GET /v1/datasets/{id}/schema (free) lists the filterable fields, their types and an example value — so you know exactly what to filter, sort and group by.03
Count, then search
count is free; search bills per record returned. Every response carries credits_used and credits_remaining.Discovery is free. You pay for records.
| Endpoint | Cost | When |
|---|---|---|
GET /v1/datasets | Free | Always |
GET …/schema | Free | Always |
POST …/count | Free | Always · cached ~5 min |
GET …/facets | Free | Always |
POST …/aggregate | Free | Always |
POST …/search | Per record | Charged per record actually returned |
GET …/record | Per match | 1 credit on a match · a miss is a free 404 |
POST …/record/bulk | Per match | Charged per match · misses are free |
| Any error response | Free | Errors are never charged |
Paid calls are pre-authorised at per_page and charged for what actually comes back.
The standard rate is 1 credit per record or match; your plan's exact per-call costs are always visible in /v1/account under costs.
New accounts start with free API credits, and you can top up any time on the pricing page. Check your balance live via /v1/account.
Limits by plan, headers on every response
Every key is rate-limited per minute and per day according to your plan — read your own limits from
/v1/account, and the live state from the X-RateLimit-* headers present on every
response. Exceeding a limit returns 429 with a Retry-After header telling you exactly
how long to back off. Upgrading your plan raises the ceiling.
# Present on every /v1 response X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 X-RateLimit-Reset: 1756900000 Retry-After: 12 # 429 only
Reference
Filterable, sortable search over any dataset. Pre-authorised at
per_page, then billed for what comes back. Use sort + per_page for "top N by field".Body parameters
filters object | See the filter reference. Field names + example values come from …/schema. |
page int · default 1 | 1-based page number. |
per_page int · default 25 · max 100 | You are billed per record returned. |
sort string | field:desc or -field. Field must be in the schema. |
fields array | Optional subset of fields to return. |
Responses
200 records page
401 bad key
402 no credits
422 bad filter / sort
404 no such dataset
429 rate limit
Response 200 (abridged)
{
"status": true,
"detail": ["ok"],
"result": {
"dataset": 79,
"total": 40005,
"page": 1,
"per_page": 2,
"records": [
{
"product_name": "Example Book",
"category": "Books",
"product_price": 12.99,
"product_rating": 4.8,
"product_reviews_count": 2411,
"url": "https://www.amazon.com/…"
}
]
},
"credits_used": 2,
"credits_remaining": 4878
}
GET/v1/datasetsFree
Every dataset available through the API:
id, name, record count and field count. Start here.GET…/{id}/schemaFree
A dataset's filterable fields, types and example values. Read it before filtering, sorting or aggregating.
POST…/{id}/countFree
Total records matching a
filters object. Cached ~5 minutes.GET…/{id}/recordPer match
Enrich: look up one record by a key field passed as a query param (e.g.
?url= or ?domain=). 1 credit on a match; a miss is a free 404.POST…/{id}/record/bulkPer match
Bulk enrich up to 100 values of one key
field in a single call. Order preserved; each item reports found. Billed per match.GET…/{id}/facetsFree
Distinct values and counts for one or more
fields (default 50, cap 500). Great for discovering valid filter values.POST…/{id}/aggregateFree
Group-by with metrics (
count, avg, min, max, sum) over numeric fields. Omit group_by for overall stats.GET/v1/accountFree
Your plan, credits remaining, per-endpoint costs and rate limits. Good first call to verify a key.
Exact, range, any-of, prefix & more
| Operator | Shape | Example |
|---|---|---|
| Exact | scalar or array (OR within a key) | {"category": "Books"} |
| Range | gt · gte · lt · lte · min · max | {"product_rating": {"gt": 3}} |
| Any-of | in | {"state": {"in": ["TX","CA"]}} |
| Not equal | ne | {"category": {"ne": "Books"}} |
| Prefix | prefix (starts-with) | {"name": {"prefix": "Jo"}} |
| Contains | contains (substring) | {"name": {"contains": "data"}} |
| Exists | exists (has any value) | {"email": {"exists": true}} |
Separate keys are AND. Field names, types and example values come from GET /v1/datasets/{id}/schema.
Text filters are case-sensitive exact matches — use the schema's example values (or …/facets to discover them).
Use range operators (gt, gte, …) for numeric fields; unknown fields or operators return 422 with guidance.
One shape, every response
{
"status": false,
"detail": [ "Unknown filter 'foo'. See …/schema." ],
"result": null,
"credits_used": 0,
"credits_remaining": 4877
}
# Same envelope for every status code,
# success and error alike.
| Code | Meaning |
|---|---|
| 401 | Missing or invalid key. Send Authorization: Bearer wa_…. Revoked keys fail within minutes. |
| 402 | Not enough credits for this call — rejected before any work runs. Lower per_page or top up. |
| 404 | No such dataset, or a record lookup miss (free). |
| 422 | Invalid filter, field, sort or operator — detail explains what to fix. |
| 429 | Rate limit hit — honour Retry-After. |
| 500 | Our fault, never charged. Retry, or contact support. |
Get started faster
Postman collection
All endpoints with ready-made example requests. Download the collection, or in Postman use Import → Link and paste that URL. Then set the
api_key collection variable to your key.API console
Exercise every endpoint from the browser with your real key — open the console. Billable endpoints charge real credits.
Reference (ReDoc)
The same specification as a readable reference — open the reference.
OpenAPI 3.0 spec
Machine-readable spec for codegen and tooling: /wapi/datasets/