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/opportunities/
• /api/notices/
• /api/entities/

Other endpoints (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¶

Approximate counts use database query-planner estimates for large result sets and fall back to exact counts 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": [...]
}