Pagination and dates

Two kinds of list

Most list endpoints page with a cursor. A few return a complete set that does not page, and truncate it with limit instead. Both shapes carry has_more and next_cursor so a single client can read either, but only the paging kind ever sets them.

Shape	How to read all of it	Endpoints
Cursor	Follow `next_cursor` until `has_more` is `false`	Brands, prompts, answers, mentions, citations
Complete set	Raise `limit` until `capped` is `false`	Topics, competitors, recommendations, generations, optimizations, audit reports, cited domains, cited pages

Cursor pagination

These endpoints return a page of results with a cursor:

{
  "data": [ { "id": "..." } ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOC0zMVQwOTo0MTowMFoifQ"
}

To fetch the next page, send next_cursor back as the cursor parameter. Repeat until has_more is false.

import os, requests

BASE = "https://api.geoptie.com"
headers = {"Authorization": f"Bearer {os.environ['GEOPTIE_API_KEY']}"}

def paginate(path, **params):
    cursor = None
    while True:
        if cursor:
            params["cursor"] = cursor
        r = requests.get(f"{BASE}{path}", headers=headers, params=params, timeout=60)
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        if not body.get("has_more"):
            return
        cursor = body["next_cursor"]

for brand in paginate("/v1/brands"):
    print(brand["name"])

Cursors are opaque. Pass them back exactly as received, and do not build, parse or store them.

Results are returned newest first.

Complete sets

The endpoints in the second row above return the whole set in one response. They have no cursor, so has_more is always false and next_cursor is always null. Here limit truncates the result rather than paging it, and two extra fields tell you whether that happened:

{
  "data": [ { "brand_name": "..." } ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1583,
  "capped": true
}

total_count is how many rows matched before limit was applied. capped is true when the response carries fewer than that, so these are the top rows and not all of them.

r = requests.get(f"{BASE}/v1/brands/{brand_id}/competitors",
                 headers=headers, params={"limit": 999}, timeout=60)
body = r.json()
if body["capped"]:
    print(f"showing {len(body['data'])} of {body['total_count']}")

Rows are ranked, so a capped response is the most significant ones rather than an arbitrary slice. Raise limit to widen it, or narrow from/to to reduce what matches.

Always check capped before reporting a total. Reading len(data) as the count is correct only when capped is false.

Dates

All dates are ISO 8601.

Parameter	Behaviour
`from`	Inclusive
`to`	Exclusive
Neither	Defaults to the last 30 days

Because to is exclusive, consecutive ranges line up without overlapping. A full month of August is from=2026-08-01&to=2026-09-01. Timestamps in responses are UTC, in the form 2026-08-31T09:41:00Z. A value that is not valid ISO 8601 returns 400 invalid_date.

Get started

Core concepts

API reference

Two kinds of list

Complete sets

Dates

Next steps

Rate limits

Errors

​Two kinds of list

​Cursor pagination

​Complete sets

​Dates

​Next steps

Rate limits

Errors

Two kinds of list

Cursor pagination

Complete sets

Dates

Next steps