GovDash
Menu

Pagination

Every list endpoint returns one page at a time, in the same shape. You request a page, read its objects, and pass a cursor back to get the next page until there are no more.

The list shape

{
  // The objects on this page, in list order.
  "edges": [
    {
      // One object. For GET /v1/opportunities, an opportunity.
      "node": {
        "id": "1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31",
        "object": "opportunity",
      },
      // Points at this object. Pass it as `cursor` to get the objects after it.
      "cursor": "eyJ2IjoxLCJhZnRlciI6IjFjOWY3YTUyIn0",
    },
    {
      "node": {
        "id": "7d3b9f15-8a2c-4e6d-b1f0-2c4e6a8b0d13",
        "object": "opportunity",
      },
      "cursor": "eyJ2IjoxLCJhZnRlciI6IjdkM2I5ZjE1In0",
    },
  ],
  // Where this page sits in the whole list.
  "pageInfo": {
    // true when more objects follow. This is the only reliable way to know.
    "hasNextPage": true,
    // true when you passed a `cursor` to get this page.
    "hasPreviousPage": false,
    // The first and last edge's cursor, or null when the page is empty.
    "startCursor": "eyJ2IjoxLCJhZnRlciI6IjFjOWY3YTUyIn0",
    "endCursor": "eyJ2IjoxLCJhZnRlciI6IjdkM2I5ZjE1In0",
  },
}

Each node is the object, shortened here. A list can leave out fields that the endpoint that retrieves one includes, such as custom_fields on opportunities or past_performance on contracts. Each list endpoint's response in the API reference shows exactly which fields it returns.

Parameters

Every list endpoint takes these two query parameters:

ParameterDescription
limitHow many objects to return, from 1 to 100. Defaults to 20.
cursorReturn the objects after this cursor. Use the previous page's pageInfo.endCursor. Leave it out to get the first page.

Cursors are opaque. Pass them back exactly as you got them, and don't save them between runs. To pick up where a previous run left off, see Sync incrementally. A cursor GovDash can't read returns 400 bad_request.

Pagination only goes forward.

Sort order

Use sort_by to choose a supported field and sort_direction=asc or desc to choose its direction. Each list endpoint in the API reference lists its allowed fields and default order. For example, opportunities default to most recently updated first, while people default to name order.

Keep the same filters, sort_by, and sort_direction when sending the next cursor. If you change them, start a new list request without a cursor. A few rules apply everywhere:

  • Lists only include objects your key can read. Records above the key's classification ceiling are left out.
  • GET /v1/meta/phases and GET /v1/meta/custom-fields also return your sub-teams' definitions. Check each one's team_id.

Filter a list

Use updated_since for incremental sync. It returns records updated at or after the supplied timestamp, including records updated at exactly that time. For example, list changed opportunities with updated_since=2026-01-01T00:00:00Z, sort_by=updated_at, and sort_direction=asc.

Agent runs also support updated_since: a run is included if it started or completed at or after the timestamp. Metadata lists support name filtering and ordering by name or order, without timestamp filters.

All seven resource lists below support updated_since. Their additional filters are:

List endpointAdditional filters
Agentsquery searches agent names; status accepts enabled or disabled.
Opportunitiesphase_id[], agency_id.
ContractsNone beyond updated_since.
Documentsstatus filters by processing status.
Agenciesname.
Companiesname.
Peoplename, email.

For opportunity phase ids, use List phases. Each endpoint's reference page lists its supported values. These parameters intentionally cover common integration needs. Email [email protected] if your integration needs another filter.

Loop through every page

Stop when hasNextPage is false. Don't stop because a page has fewer objects than limit.

paginate.tsTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

const headers = {
  Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
  "govdash-version": apiVersion,
}

async function* listAll(path: string, params: Record<string, string> = {}) {
  let cursor: string | null = null
  do {
    const query = new URLSearchParams(params)
    if (cursor !== null) query.set("cursor", cursor)
    const response = await fetch(
      `${process.env.GOVDASH_API_URL}${path}?${query}`,
      { headers },
    )
    if (!response.ok)
      throw new Error(`${response.status}: ${await response.text()}`)
    const page = await response.json()
    for (const edge of page.edges) yield edge.node
    cursor = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null
  } while (cursor !== null)
}

for await (const opportunity of listAll("/v1/opportunities")) {
  console.log(opportunity.id, opportunity.title)
}
paginate.pyPython
import os

import requests


def list_all(path, params=None):
    session = requests.Session()
    session.headers["Authorization"] = "Bearer " + os.environ["GOVDASH_API_KEY"]
    session.headers["govdash-version"] = os.environ["GOVDASH_API_VERSION"]
    query = dict(params or {})
    while True:
        response = session.get(os.environ["GOVDASH_API_URL"] + path, params=query)
        response.raise_for_status()
        page = response.json()
        for edge in page["edges"]:
            yield edge["node"]
        if not page["pageInfo"]["hasNextPage"]:
            return
        query["cursor"] = page["pageInfo"]["endCursor"]


for opportunity in list_all("/v1/opportunities"):
    print(opportunity["id"], opportunity["title"])

For a full example that also handles rate limits, see Export opportunities from GovDash.

If you're paging through everything on a schedule to find what changed, there's a better way. See Sync incrementally.