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. Only these high-volume endpoints use approximate counting by default:

• /api/contracts/
• /api/idvs/
• /api/opportunities/
• /api/notices/

All other endpoints (entities, agencies, offices, grants, forecasts, subawards, vehicles, etc.) always return exact counts. The ?exact=true parameter has no effect on these endpoints — they are already exact.

How approximate counts work¶

Approximate counts use PostgreSQL query planner estimates for large result sets and fall back to exact COUNT(*) for small ones (typically under 1,000 rows). This means even the endpoints listed above often return exact counts when the result set is small enough.

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.

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.makegov.com/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.makegov.com/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.makegov.com/api/entities/" | grep X-Results

X-Results-CountType: exact

{
  "count": 487293,
  "next": "...",
  "results": [...]
}