Query Parameters

Default to cursor mode for anything that's not a small, paginated UI list. Cursor (keyset) mode is dramatically faster at scale:

The numbers are from a 6M-plot stress benchmark — your mileage will vary, but the curve is the same: cursor is O(page_size); page-number scales with how deep you've paged (skipping to a deep page gets slower the further in you go).

• Page-number is fine for small result sets and known-shallow paging. The server computes a total so UIs can render "page X of Y".
• Cursor (keyset) is the right choice for large result sets, deep pagination, full-dataset walks, and any list endpoint backing a non-UI integration. Each request is O(page_size) regardless of how far you've paged — page 10 and page 10,000 take the same time. The server skips the total-count step entirely, so meta.total is null on cursor responses — use meta.has_next / meta.next_cursor to traverse.

You opt into cursor mode by passing ?page[cursor]= (empty value = first cursor page; subsequent calls echo back the value from meta.next_cursor). Page-number responses never include meta.next_cursor — switching modes mid-traversal requires re-issuing the request with ?page[cursor]= (the server doesn't auto-promote between modes).

List endpoints return rows in lexicographic order by location id, ascending, on both pagination modes. This is stable and identical between page-number and cursor traversal — switching modes (or even refreshing the same page) returns results in the same order.

Applies to /locations/{facilities,sheds,plots} and /metrics/<type>/<metric> (the "latest per location" shape). Both use the same location-id ascending sort.

The untyped mixed /locations listing and the streaming endpoint still sort by creation time (newest first), then by location id, for backwards-compat with cursor-stream callers. If you need rows sorted by monitoring_end (newest data first), call the per-metric /history endpoint with filters or sort client-side after fetching a page.

Some list endpoints accept a JSON:API-style sort parameter to override the default order:

?sort=-noncompliance_plot_count     # descending
?sort=created_at                    # ascending

• A leading - means descending; otherwise ascending.
• NULLs are ordered by direction: DESC → NULLS LAST, ASC → NULLS FIRST — unless a key documents an override (e.g. GET /ingestions sorts name NULLS LAST in both directions, so unnamed tasks always sort last).
• The order is always made total by appending the resource id as the final tie-break, so pagination (offset and cursor) is stable.
• The sort key is added to the cursor payload, so ?sort=… composes with page[cursor]= — keyset pagination stays correct at any depth.
• Only the keys listed below are accepted per endpoint. Any other key returns 400 (the same shape as an unsupported filter), and a ?sort= on an endpoint that doesn't list it is rejected too.
• Omitting sort keeps each endpoint's default order (above) — fully backward compatible.

Allowed sort keys by endpoint

Sorting metric time fields (monitoring_end_date, etc.) and other location/metric attributes is not yet supported — those keys return 400 until backing indexes (or denormalised sort columns) land. See the engineering follow-ups.

// Page-number mode — request: `?page[number]=1&page[size]=100`
{
  "meta": {
    "page": 1,
    "page_size": 100,
    "total": 1250,
    "has_next": true,
    "total_is_approx": false
  },
  "links": {
    "self": "/locations/facilities?page[number]=1&page[size]=100",
    "next": "/locations/facilities?page[number]=2&page[size]=100"
  },
  "data": [...]
}

// Cursor (keyset) mode — request: `?page[size]=100&page[cursor]=`
{
  "meta": {
    "page": 1,
    "page_size": 100,
    "total": null,
    "has_next": true,
    "next_cursor": "550e8400-e29b-41d4-a716-446655440000"
  },
  "links": {
    "self": "/locations/facilities?page[size]=100&page[cursor]=",
    "next": "/locations/facilities?page[cursor]=550e8400-e29b-41d4-a716-446655440000&page[size]=100"
  },
  "data": [...]
}

# First page (page-number mode — server also gives you a cursor to switch)
curl '/locations/plots?filter[assets.task_id]=eq:<task>&page[size]=50' \
  -H 'x-api-key: ...'
# → meta.next_cursor: "0000389d-43b0-4b31-bf51-22bcaade16b7"
# → links.next: "/locations/plots?...&page[cursor]=0000389d-...&page[size]=50"

# Follow the cursor — same shape, no deep-paging cost
curl '/locations/plots?filter[assets.task_id]=eq:<task>&page[size]=50&page[cursor]=0000389d-...' \
  -H 'x-api-key: ...'

Stop when meta.next_cursor is absent (or links.next is omitted). Each cursor page costs the same as the first, even at "page 10,000" equivalent depth.

/locations/*, /metrics/<location_type>/<metric>, and GET /ingestions (the asset-task list) all support cursor pagination on an identical contract. /ingestions defaults to created_at ASC, id ASC and folds any ?sort= key into the cursor, so keyset traversal stays correct at any depth — see its allowed sort keys. Resuming an /ingestions cursor requires an explicit ?sort= spec; a cursor without one returns 400.

When using streaming response formats (application/x-ndjson or application/x-ndgeo+json), pagination parameters are ignored and all matching results are streamed in one response. See Response Formats for the streaming wire format and how to consume it.

filter[<attribute>]=<condition>:<value>

If the condition is omitted, eq is assumed:

filter[name]=Fazenda        # equivalent to filter[name]=eq:Fazenda

For endpoints with nested data fields (e.g. assets.data), use dot-notation to filter by nested fields:

filter[assets.data.CITY]=eq:London
filter[assets.data.address.city]=contains:New
filter[assets.data.score]=gte:80

The first segment identifies the data field; subsequent segments navigate into nested keys. Each endpoint documents which wildcard prefixes are supported (e.g. assets.data.*).

Some endpoints support filtering by related resource attributes using dot-notation with the relationship name:

filter[location.location_type]=eq:facility
filter[location.commodity_type]=eq:palm

These are documented per-endpoint under the Query parameters section.

Location (/locations, /locations/{facilities,sheds,plots}) and metric (/metrics/{plots,sheds,facilities}/<metric>) endpoints can be filtered by supplier:

filter[supplier_id]=eq:<supplier-uuid>            # global supplier ID
filter[supplier_id]=in:<uuid-a>,<uuid-b>
filter[supplier_external_id]=eq:<your-supplier-id> # your org-local identifier
filter[supplier_external_id]=startsWith:ACME-

• supplier_id is the global supplier UUID returned by GET /parties/suppliers.
• supplier_external_id is the identifier you supplied for the supplier in your own namespace (e.g. a supplierid column at upload, or external_id on the supplier object). For best performance prefer eq / in / startsWith — contains cannot use the supplier index.
• Drill-through-parents: on the typed /locations/sheds, /locations/plots and the corresponding /metrics/{sheds,plots}/… routes, a location also matches when an ancestor (its parent facility, or a plot's parent shed) is linked to the supplier — so a supplier attached at facility or shed grain still surfaces its descendant plots/sheds. On /locations/facilities, the bare /locations route, and /metrics/facilities/…, only the location's own supplier link is matched.
• All supplier filtering is organization-scoped: you only ever match suppliers linked within the orgs you can access.

Deforestation metric endpoints accept filter[deforestation_period] to select which monitoring period to return. A plot uploaded with a start_date far from the EUDR cut-off produces two rows — a user-period row and an EUDR-period row (see Metric Methodology — How is_compliant is computed).

filter[deforestation_period]=eq:eudr   # only EUDR-assessment rows (is_compliant meaningful)
filter[deforestation_period]=eq:user   # only user-period rows (since your own start_date)

Applies to /metrics/{plots,sheds,facilities}/deforestation (latest, /history, /:commodity, streaming). It is deforestation-only — silently ignored on other metric families — and facility aggregates are EUDR-anchored, so eq:user returns no rows there. Omit the filter for the default "latest" behaviour.

GET /ingestions/assets (and GET /ingestions/assets/:id) accept filter[compliance] to narrow the list by each item's per-location EUDR deforestation status:

filter[compliance]=eq:non_compliant   # items whose location has ≥1 non-compliant plot
filter[compliance]=eq:pending         # no non-compliant plot, ≥1 awaiting review
filter[compliance]=eq:compliant       # every non-excluded plot has a compliant result
filter[compliance]=eq:excluded        # every plot excluded from the filing
filter[compliance]=eq:not_assessed    # some plot has no result yet, or no EUDR plots

The statuses are checked in this order, and the first that applies wins, so the five values partition the set:

• Same vocabulary as filter[compliance] on GET /ingestions (task grain); here it is per location (a facility/shed rolls up its catchment; a plot location rolls up the parts of its latest upload).
• Evaluated against the same variant as the ?deforestation= view — pin it with ?deforestation=ccdc/eudr, else the prioritised fallback applies. Facility/shed read the cached roll-up; plots evaluate live.
• meta.total reflects the filter. eq only.

The two headline risk levels promoted onto the assessments relationship — legality_risk_level (Article 9 adverse-media / legality) and article10_risk_level (Article 10 country-risk) — are filterable on both the per-record and the location grain:

# Records whose location's headline legality risk is high
GET /ingestions/assets?filter[assessments.legality_risk_level]=eq:high

# Facilities at medium or high Article 10 country-risk
GET /locations/facilities?filter[article10_risk_level]=in:medium,high

• Values: low, medium, high (enum; eq and in).
• The filter matches the promoted level the row displays (canonical field first, sco2api alias fallback), so a filtered list can never disagree with the levels returned under include=assessments / include=assessment.
• Rows with no visible art9/art10 assessment never match any value — there is no "unassessed" filter value. Absence isn't filterable; it's just the null level on the row.
• On GET /ingestions/assets* the attributes are assessments.legality_risk_level / assessments.article10_risk_level (matching the confidence filters); on the typed /locations/* routes they are plain legality_risk_level / article10_risk_level.
• Both keys are also sortable on the same endpoints (severity-ranked; see the sort-key table above).

• Only attributes listed per-endpoint are accepted. Unsupported attributes return a 400 Bad Request with a VALIDATION_ERROR code.
• The condition must be one of the values listed above.
• The value (operand) must be non-empty.
• Each attribute enforces type-specific validation on both the condition and the value. Using an unsupported condition or invalid value returns a 400 Bad Request with a descriptive error message.

Each filterable attribute has a type that determines which conditions are allowed and how the value is validated.

Tag filters (filter[tags]=…) are dramatically faster on the typed routes (/locations/{facilities,sheds,plots}, /metrics/<type>/<metric>) than on the untyped /locations mixed listing. The typed routes scan only the matching pivot + resource_tag combination; the untyped route has to UNION across all three pivot tables (facility, shed, plot) because the request can legitimately return any of those types.

At 6M-plot stress scale, an ?filter[tags]=in:high-priority query takes 200ms-1.4s on a typed route vs ~14s on the untyped /locations route. If you know the location type you want, use the typed route. If you're consuming a mixed listing, expect tag-filter responses to be 10-50× slower than the same filter on a typed route.

Invalid condition for attribute type:

filter[country_code]=gt:BR
→ 400: "Filter condition 'gt' is not supported for attribute 'country_code'. Allowed conditions: eq, in"

Invalid enum value:

filter[overall_status]=eq:unknown
→ 400: "Invalid value 'unknown' for filter 'overall_status'. Allowed values: pending, processing, validating, completed, failed"

Numeric value out of range:

filter[validation.confidence_score]=gt:2
→ 400: "Value 2 for filter 'validation.confidence_score' exceeds maximum 1"

Invalid UUID format:

filter[id]=eq:not-a-uuid
→ 400: "Invalid UUID format for filter 'id': not-a-uuid"

String value too long:

filter[name]=eq:<256+ characters>
→ 400: "Value for filter 'name' exceeds maximum length of 255 characters"

fields[<resource>]=<attr1>,<attr2>,...

GET /locations/facilities?fields[facility]=name,country_code

Returns facility resources with only name and country_code in attributes. The top-level type, id, links, and relationships fields are always present regardless of field selection.

On the /metrics/... list routes, pass include_links=false as well to keep only links.self on each row and drop the per-row navigation links.

• Only resource types and attributes listed per-endpoint are accepted.
• At least one attribute must be specified.
• Unsupported resource types or attributes return a 400 Bad Request.

include_geometries=true

Accepted values are true and false (default false). Any other value is a 400 Bad Request.

So you never need the flag when requesting a GeoJSON media type; you only need it to add geometry to a plain JSON / NDJSON response.

# Default — no geometry, `geo` absent from attributes
GET /locations/plots

# Opt in — `geo` present on every resource
GET /locations/plots?include_geometries=true

# geo+json always carries geometry, flag or not
GET /locations/plots
Accept: application/geo+json

On GET /ingestions/assets and GET /ingestions/assets/:id, geometry lives inside the normalised_data relationship. It therefore requires both include=normalised_data and include_geometries=true:

GET /ingestions/assets/{id}?include=normalised_data&include_geometries=true

Passing include_geometries=true without include=normalised_data is a no-op there (the relationship that would carry the geometry isn't expanded).

Migration note. Prior to this change, geo was always present in JSON responses. Clients that read attributes.geo (or normalised_data's geometry) from a plain JSON/NDJSON response must now pass include_geometries=true, or switch to a geo+json media type.

include=<relationship1>,<relationship2>

• Only relationship names listed per-endpoint are accepted.
• Unsupported relationship names return a 400 Bad Request.

asset_data is combined column by column. For each field in your uploaded data, the rolled row looks across every plot in the upload:

• if the value is the same on every plot, the field keeps that single value;
• if the value differs between plots, the field becomes the list of the distinct values found.

So a country column that is BR on all plots stays "country": "BR", while a producer_name that varies becomes "producer_name": ["Farm X", "Farm Y"].

Very high-cardinality fields are capped — the list is truncated and the field name is added to a reserved _truncated list on the row (a "*" entry there means the upload was large enough that the sample itself was capped).

A folded row still needs a single location, geometry, and assessment result to show. The API uses the upload's first plot — the earliest-resolved plot in the upload — as the representative:

• location_id / location_type, the normalised_data relationship, the assessments relationship, and the map geometry all come from that first plot;
• asset_data (above) still reflects all the plots.

So you get one plot's full detail alongside the combined data for the whole upload.

?rollup=true accepts the same filter[...] and ?sort= parameters as the un-rolled list. Both are applied at plot grain, before the fold:

• Filters narrow the plots that make up each rolled row. A plot upload appears only if at least one of its plots matches, and the fold — the asset_data columns, the representative "first plot", and the counts — then summarises only the matching plots. (Facility/shed rows filter directly, as on the un-rolled list.) For example, filter[has_location]=eq:true folds only the resolved plots of each upload, and an upload with no resolved plot drops out entirely.
• Sorting orders rolled rows by an aggregate of their matching plots. sort=legality_risk_level / article10_risk_level orders each upload by its worst plot risk; created_at, status, and source_file sort on the upload's own value. A single sort key is honoured (the list sorts one column at a time).

• deforestation (with include=deforestation) is the whole upload's roll-up (all its plots together) — not just the first plot's verdict.
• collection_ids are the distinct plot-collection hashes for the upload.

• id on a rolled row is the ingestion task id; links.self points at that task's assets and links.location at the representative plot.
• Works with page-number and cursor pagination, and across all four response formats — JSON, application/geo+json, and the streaming application/x-ndjson / application/x-ndgeo+json variants. (Streaming pages the fold internally under a cursor, so memory stays bounded to one page.)

• Only the first ?sort= key is applied; multi-key sort under rollup falls back to that key plus the row id as a tie-break.
• deforestation on a rolled row is the whole upload's roll-up even when a filter narrows the fold — it is not re-scoped to the matching plots.

GET /ingestions/assets?rollup=true&include=normalised_data,deforestation

{
  "type": "asset",
  "id": "<plot upload/task id>",
  "attributes": {
    "asset_data": {
      "commodity": "cocoa",                    // same on every plot → one value
      "country_code": "BR",
      "name": ["Plot A", "Plot B", "Plot C"]   // differs → list of distinct values
    },
    "location_id": "<first plot's id>",         // representative first plot
    "location_type": "plot",
    "deforestation": { "total_plots": 3, "compliant_plots": 3 },  // whole upload
    "collection_ids": ["0xf151…"]
  },
  "relationships": { "normalised_data": { /* first plot */ } }
}

?rollup=unit folds rows onto the supplier unit instead of the upload. A supplier unit is the group of locations that validation assigns to one supplier at ingest. A plot upload that holds three supplier units returns three rows. Each row folds only the plots of its own unit.

The grain is (organization_id, upload, supplier unit):

• The same unit in two uploads stays two rows.
• Two organisations never share a row, even when their unit ids are equal.

The fold, filters, sort and pagination work the same as under rollup=true, at the unit grain.

GET /ingestions/assets?rollup=unit&filter[assets.task_id]=eq:<task id>&include=normalised_data,deforestation

{
  "data": [
    {
      "type": "asset",
      "id": "db0eb544-7791-3eb4-8f67-978d73bb854f",   // synthetic unit-row id
      "attributes": {
        "asset_task_id": "<task id>",
        "asset_data": { "country_code": "BR", "name": ["Plot A1", "Plot A2"] },
        "deforestation": { "total_plots": 2, "compliant_plots": 2 },   // this unit only
        "live_plot_count": 2
      },
      "relationships": {
        "normalised_data": { "attributes": { "supplier_unit": "5ae3999c8cdc" } }
      }
    },
    {
      "type": "asset",
      "id": "d1456a0a-2b75-38e0-8f2a-41907fecff11",
      "attributes": {
        "asset_task_id": "<task id>",
        "asset_data": { "country_code": "ID", "name": "Plot B1" },
        "deforestation": { "total_plots": 1, "non_compliant_plots": 1 },
        "live_plot_count": 1
      },
      "relationships": {
        "normalised_data": { "attributes": { "supplier_unit": "b8d633605518" } }
      }
    }
  ]
}

curl -H "x-api-key: sk-epoch-..." \
     -H "Accept: application/x-ndjson" \
     "https://api.epoch.blue/locations/facilities?filter[commodity]=eq:soy"

Each line is a complete JSON object:

{"type":"facility","id":"a1b2...","attributes":{"name":"Porto Plant","commodity":"soy",...}}
{"type":"facility","id":"c3d4...","attributes":{"name":"Santos Mill","commodity":"soy",...}}

import requests

response = requests.get(
    "https://api.epoch.blue/locations/facilities",
    headers={
        "x-api-key": "sk-epoch-...",
        "Accept": "application/x-ndjson",
    },
    params={"filter[commodity]": "eq:soy"},
    stream=True,
)

for line in response.iter_lines():
    if line:
        record = json.loads(line)
        print(record["attributes"]["name"])