Querying the API

A queryable endpoint takes seven reserved parameters. Everything else in the query string is read as a filter on a field of that resource. An unrecognised parameter is rejected with a 400 rather than ignored, so a typo cannot quietly return you the unfiltered dataset and bill it to your quota.

select narrows the response to the fields you name, in the order you name them. On a large pull this is the single cheapest optimisation available: it cuts transfer size, parse time, and the memory your job needs.

Field names are validated against the resource. An unknown name returns a 400 that lists every available field, so you can discover a resource's shape from an error rather than from guesswork. select=* is deliberately not supported: naming your fields keeps your integration stable when we add columns.

A small number of fields carry individual contact data and are never in the default projection. They are available on paid plans only, and only when you request them explicitly. Asking for one on a free key returns field_not_entitled naming the field.

Filters are written field[operator]=value. The bare form, field=value, means equals. Multiple filters combine with AND.

Values are validated against the field's type before the query runs, so a bad value returns a clear 400 rather than a database error. In patterns, * is the only wildcard: your % and _ are matched literally.

sort=-recorded_on,parcel_id sorts by recorded_on descending, then parcel_id ascending. The field:desc spelling works too. Up to four keys.

Sorting is restricted to indexed columns. Ask for one that is not indexed and you get an explicit sort_not_indexed error listing the columns that will work, instead of a request that scans a multi-million row table and times out with no explanation. If you need an ordering we do not index, tell us which one and we will look at adding it.

Nulls always sort last, in both directions, so a page boundary means the same thing on every request.

Two modes. Offset paging (limit and offset) is right for jumping to a known page of a small result set. Cursor paging is right for everything else, and it is the only way to read a large dataset end to end.

Offset paging has a hard ceiling. Past it we return offset_too_large rather than accepting the request, because a deep offset makes the database produce and discard every skipped row: the cost grows with depth until it times out. That is a real limit of offset paging, not a plan restriction, and cursors remove it entirely.

Every response carries a page envelope:

has_more is a fact, not an estimate: we read one row beyond your page to determine it. You never need a trailing empty request to discover you finished.

Take page.next_cursor from a response and pass it back as cursor. Repeat until has_more is false. Each page costs the same whether it is the first or the fifteen thousandth.

Three rules for cursors:

• A cursor is opaque. Pass it back byte for byte. It is signed, so an edited cursor is rejected rather than silently returning the wrong slice.
• Do not change your filters or sort mid-walk. A cursor is only meaningful under the query it was issued for, so we return cursor_mismatch instead of a wrong answer. Change the query, start the walk again.
• cursor and offsetcannot be combined, and a cursor walk runs in the resource's cursor order. If you need a different ordering, use offset paging.

Cursors are available on every plan, including free. Your monthly request quota is the meter, not your ability to paginate.

total is an object, not a bare number, because you need to know how much to trust it:

• count=exact runs a real count. exact is true. Accurate, and on a multi-million row dataset it is usually the most expensive part of the request.
• count=estimatedreturns the query planner's estimate. exact is false and source says planner_estimate. Free, and on a filtered query it can be off by a wide margin. Fine for a progress bar, not for reconciliation.
• count=none skips counting. valueis null, never zero, so "we did not count" is never confused with "nothing matched". Use this for cursor walks: the total does not change per page.

We never return an estimate labelled as exact. If a plan limit causes an exact count to be downgraded, total.note says so on that response.

updated_since returns only rows modified at or after an ISO timestamp. A bare date is read as midnight UTC. Combined with a cursor walk, this is the whole daily-delta pattern:

Record the largest updated_atyou received and use it as the next run's updated_since.

How far back updated_since can reach depends on your plan. If your request reaches further back than your plan allows we clamp it forward and say so in meta.notes on that response. We never truncate a delta silently, because a sync that quietly misses rows is worse than one that fails.

Every query response carries an ETag. Send it back as If-None-Match and, if nothing changed, you get a 304 with no body.

The ETag covers the rows, the total and your pagination position. It does not change when only plan copy or rate-limit context changes, so it stays useful.

One thing to be clear about: a 304 still counts as one request against your monthly quota. We authenticate and run the query before we can tell whether anything changed. What a 304 saves is transfer and parse time, which on a large page is the expensive part.

Every response tells you where you stand.

On an unmetered key the numeric headers are omitted and X-RateLimit-Policy reads unmetered, so a client parsing these as integers never sees a non-numeric value.

Errors keep the shape used everywhere else in the API: { ok: false, error, message }, plus extra fields that tell you what to do next. A rejected filter lists the filterable fields, a rejected sort lists the sortable ones, a rejected value lists the allowed values.

Page size, offset depth, how far updated_since reaches back, and access to fields carrying individual contact data all vary by plan. Your plan is resolved on every request, and when a limit shortens a response we say so in meta rather than trimming quietly. An oversized limit is clamped and reported, not refused.

See plans and pricing for the current numbers, or the full API reference for each endpoint's fields and scopes.