Skip to main content

Query API quickstart

Applies toQuery API

The Query API is the synchronous REST surface: you send a request and the data comes straight back in the same response. It serves both option-level records and aggregated stats, depending on the endpoint; this guide starts with the options endpoint. Not sure this is the surface you want? See MCP or the API?.

1. Get your access key​

Every request carries your EDITED access key in the x-api-key header — the same key across MCP, the Query API, and the Jobs API. If you don't have one yet, see Authentication & access.

2. Make your first request​

The most direct first call is options — filter for a set of products and get their option documents back. It's a POST, with the filter in the request body:

curl -s -X POST "https://apis.edited.com/query/v1/apparel/options?size=15" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "filters": { "in_stock": true } }'

A few things to know about that request:

  • The vertical is in the path. apparel here — swap it for beauty or homeware to match the data domain you're licensed for.
  • filters is how you scope the query. An empty object ({}) matches everything; { "in_stock": true } narrows to in-stock products. The full mechanics — ranges, excluding with not_, and how filter names map to fields — are in Filters. Filters like retailer and brand_slug take resolved slugs, not free-text names (brand is the free-text one: pass the brand's name there, never a slug); see Resolving values.
  • size sets how many results come back. It defaults to just 10, so set it explicitly when you want more.

3. Read the response​

The response is a JSON object with two keys:

  • data — the list of matching option documents. Each field is defined in the data dictionary.
  • meta — information about the query, including docs, the total number of documents that matched your filter.

One thing catches people out on a first read:

  • meta.docs is the true match count; the length of data is only what this response returned. Because size defaults to 10, a query matching thousands of products still returns 10 items unless you raise size — so compare the two rather than assuming you received everything. A single response is capped at 10,000 records; to pull more, paginate (see Rate limits → Query API).

4. Where to go next​

If you want to…Go to
Reproduce an exact EDITED Market chart or statisticthe stats endpoints in the API reference
Pull more than 10,000 records, or handle rate limitsRate limits & fair use
Resolve brand / retailer / category names to filter valuesHow to query · Filters
Understand every field in an option documentData dictionary
See every endpoint and its request shapeAPI reference
Bulk or historical over-time extraction insteadJobs API quickstart
Reaching for summary stats?

For general stats and summaries, MCP is usually the quicker route — it's interactive and self-documenting. The Query API's stats endpoints are the right tool when you need to reproduce a specific EDITED Market visualization or pull the exact aggregation behind an app chart. See MCP or the API? for the full comparison.

Still stuck on your first call? Contact support@edited.com.