Filters

Applies toQuery APIJobs API

Filters are how you tell EDITED which options to return (or collect stats for). They provide the same control as the filter panel in the EDITED app, expressed as JSON. This page covers how filtering works; for the exact filter names and valid values, see the references linked below.

Using MCP?

The MCP tools take their filters as tool parameters, not a filters object. Use the market_data_docs tool (topic filter_fields) for the MCP filter vocabulary. The structure below applies to the Query API and the Jobs API.

The filters object

Filters go in the request body as a JSON object — each key is a filter, each value is what to match. The structure is identical across the REST surfaces; only the wrapping key differs: the Query API calls it filters, the Jobs API calls it legacy_filters. The examples below use filters; for a Jobs request, put the same contents under legacy_filters.

{
  "filters": {
    "in_stock": true,
    "retailer": ["retailer_slug_a", "retailer_slug_b"]
  }
}

The matching rules:

• Different filters are combined with AND. The example above returns options that are in stock and from one of the two retailers.
• A list of values for one filter is OR. retailer above matches retailer_slug_a or retailer_slug_b.

Filter names aren't always the field name

A filter's name usually matches the field it filters — but not always, so don't assume a dictionary field name works verbatim as a filter:

• Range filters add a _range suffix. The filter for the date_found field is date_found_range; for discount_percentage it's discount_percentage_range; and so on for the other numeric and date fields (see Ranges below).
• List and boolean filters use the field name as-is — brand, retailer, in_stock, discounted.
• Some filters have no field counterpart, and some fields aren't filterable at all.

The data dictionary documents the response fields — what comes back in an option. The authoritative filter vocabulary (every filter name and its valid values) lives with the surfaces:

• API reference — the Query and Jobs request payloads list the filters each endpoint accepts.
• market_data_docs (topic filter_fields) — the MCP filter reference, with valid values and operators.

Ranges

Range filters take an object with any of gte, gt, lte, and lt (greater-than-or-equal, greater-than, less-than-or-equal, less-than). Remember the name carries the _range suffix:

{
  "filters": {
    "date_found_range": { "gte": "2020-01-01", "lte": "2020-01-31" }
  }
}

Pass a list of range objects to match any of several ranges — for example, options first seen in January 2018 or January 2019:

{
  "filters": {
    "date_found_range": [
      { "gte": "2018-01-01", "lt": "2018-02-01" },
      { "gte": "2019-01-01", "lt": "2019-02-01" }
    ]
  }
}

Excluding with not_

Any filter can take a not_ prefix to exclude rather than include — this works on list, boolean, and range filters alike. To return options from anywhere except two retailers:

{
  "filters": {
    "not_retailer": ["retailer_slug_a", "retailer_slug_b"]
  }
}

You can combine a not_ filter with a positive one in the same request — for example, in stock ("in_stock": true) but not from a given retailer ("not_retailer": ["retailer_slug_a"]).

Resolving values

Many filters take EDITED slugs or IDs, not free text — retailer, brand, category, and size filters all expect resolved identifiers. Passing a free-text name where a slug is expected will either fail or match the wrong thing, so resolve the identifiers first.

You can use either surface for this — and you can mix them. The slugs and IDs are the same whether you look them up over REST or over MCP, so even when you're building on the REST API you're welcome to resolve values with the MCP search tools and drop the result straight into a REST filter. It's a common, fully supported pattern.

• REST — the Schema API discovery endpoints (brands, retailers, searches, details).
• MCP — the search_* tools (search_retailers, search_brands, and so on).

Either returns the same identifiers. See How to query for the resolution pattern.

Excluding inferred data

To restrict a query to freshly observed data, exclude inferred records with "not_inferred": true. See the inferred field.