Skip to content

Result counts

Every paginated response includes a count field with the total number of matching results. The X-Results-CountType response header indicates whether that count is exact or approximate.

Which endpoints use approximate counts?

Most endpoints always return exact counts. These high-volume endpoints use approximate counting by default:

  • /api/contracts/
  • /api/idvs/
  • /api/assistance/grants/, /api/assistance/loans/, /api/assistance/direct_payments/, /api/assistance/other/
  • /api/opportunities/
  • /api/notices/

Other endpoints (entities, grants, subawards, vehicles, protests, etc.) always return exact counts. The ?exact=true parameter has no effect on those — they're already exact. Inspect the X-Results-CountType response header (exact or approximate) on any request to confirm.

How approximate counts work

On the endpoints above, a filtered request is counted exactly up to 10,000 results, so most filtered searches return an exact count and X-Results-CountType: exact.

Past 10,000 results the count is approximate: a database query-planner estimate, never lower than 10,001. Read it as "at least 10,001" rather than a precise size, and add ?exact=true when you need the real figure.

An unfiltered request (for example, every contract) returns an approximate count taken from table statistics.

Requesting exact counts

For the endpoints that use approximate counting, add ?exact=true to force an exact count:

GET /api/contracts/?exact=true
GET /api/opportunities/?exact=true&search=software

Performance note: Exact counts run a full COUNT(*) query, which can be slow on large, unfiltered result sets (e.g., all contracts). Use this when accuracy matters more than speed.

Pagination does not depend on the count: next is present as long as more results exist, with or without ?exact=true, so you can page to the last result either way.

Knowing whether a count is exact

Check the X-Results-CountType response header:

X-Results-CountType: exact
X-Results-CountType: approximate

This header is present on all paginated list responses. It is not included on detail (single-resource) endpoints.

Examples

Contracts (approximate by default)

curl -sI -H "X-API-KEY: your-key" \
  "https://tango.dev/api/contracts/" | grep X-Results
X-Results-CountType: approximate
{
  "count": 2541837,
  "next": "...",
  "results": [...]
}

Contracts with exact count

curl -sI -H "X-API-KEY: your-key" \
  "https://tango.dev/api/contracts/?exact=true" | grep X-Results
X-Results-CountType: exact
{
  "count": 2541293,
  "next": "...",
  "results": [...]
}

Entities (always exact)

curl -sI -H "X-API-KEY: your-key" \
  "https://tango.dev/api/entities/" | grep X-Results
X-Results-CountType: exact
{
  "count": 487293,
  "next": "...",
  "results": [...]
}