Export Page Analytics

POST /functions/v1/export-page-analytics

Beta. This endpoint is new and its response shape may still change. It is the page-level companion to Export Crawl Analytics: same authentication and time windows, but broken down by page instead of aggregated per domain.

Returns the pages of one domain ranked by bot crawl volume. Each page carries its verified / declared / unknown tier split, a per-bot breakdown, and (by default) a bucketed time series. Because a domain can have thousands of crawled paths, this endpoint is single-domain and cursor-paginated — it does not have an account-wide mode.

Always call this endpoint from a server-side environment (backend API, serverless function, build script, etc.). Never include your API key in client-side code — it will be visible to anyone inspecting your frontend.

Programmatic (API key) access requires the Pro plan and above — requests from Starter accounts return 403 plan_upgrade_required.

Page-level crawl data begins on 2026-07-09 (legacyCutover). Windows that start earlier are automatically clamped to that date (the response echoes your original start as requestedStartDate); windows that end before it return 400 invalid_request.

Request

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer hado_sk_your_key_here`
`Content-Type`	Yes	`application/json`

Body Parameters

Parameter	Type	Required	Description
`domainId`	string	Yes	The domain to export. Get IDs from List Domains.
`period`	string	No	Rolling window ending today: `1d`, `7d`, `30d`, `90d`, or `365d`. Defaults to `30d`. Cannot be combined with `startDate`/`endDate`.
`startDate`	string	No	Start of an explicit date range, `YYYY-MM-DD` (UTC, inclusive).
`endDate`	string	No	End of an explicit date range, `YYYY-MM-DD` (UTC, inclusive). Optional — defaults to today when `startDate` is supplied. Cannot be sent without `startDate`.
`granularity`	string	No	Series bucket size: `auto` (default), `day`, or `week`. `auto` picks `day` for windows up to 90 days and `week` beyond. Requesting `day` for a longer window is a `400`.
`sortBy`	string	No	Page ranking: `total` (default) or `verified`.
`pageSize`	number	No	Pages per response, `1`–`500`. Defaults to `50`.
`series`	boolean	No	Include the per-page time series. Defaults to `true`; set `false` for a lighter, aggregate-only payload.
`botId`	string \| string[]	No	Only count crawls from these bots (e.g. `"gptbot"` or `["gptbot", "claudebot"]`). Also switches the series to a per-bot breakdown.
`tier`	string \| string[]	No	Only count crawls in these tiers: `verified`, `declared`, `unknown`.
`pathPrefix`	string	No	Only include paths starting with this prefix (e.g. `"/blog/"`). Matched literally — `%` and `_` have no special meaning.
`cursor`	string	No	Continuation token from a previous response’s `nextCursor`. When set, all other parameters except `series` are taken from the cursor — it pins the window, granularity, sort, filters, and page size so later pages stay consistent with the first.

Window rules (same as the other export endpoints): period and startDate/endDate are mutually exclusive, dates must be real YYYY-MM-DD calendar dates, neither may be in the future, startDate ≤ endDate, and the span is capped at 365 days.

Example Request

First page:

curl -X POST https://api.hadoseo.com/functions/v1/export-page-analytics \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "11111111-1111-1111-1111-111111111111",
    "period": "30d"
  }'

Next page — just the cursor:

curl -X POST https://api.hadoseo.com/functions/v1/export-page-analytics \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cursor": "eyJ2IjoxLCJkIjoiMTExMTExMTEt..."
  }'

Only GPTBot crawls of the blog, ranked by verified volume:

curl -X POST https://api.hadoseo.com/functions/v1/export-page-analytics \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domainId": "11111111-1111-1111-1111-111111111111",
    "period": "90d",
    "botId": "gptbot",
    "pathPrefix": "/blog/",
    "sortBy": "verified"
  }'

Response

Success (200)

{
  "generatedAt": "2026-07-31T12:00:00.000Z",
  "period": "30d",
  "startDate": "2026-07-02",
  "endDate": "2026-07-31",
  "granularity": "day",
  "userId": "00000000-0000-0000-0000-000000000000",
  "legacyCutover": "2026-07-09",
  "domain": "example.com",
  "domainId": "11111111-1111-1111-1111-111111111111",
  "role": "owner",
  "pageCount": 4210,
  "pages": [
    {
      "path": "/pricing",
      "total": 940,
      "tiers": { "verified": 700, "declared": 200, "unknown": 40 },
      "bots": {
        "googlebot": { "verified": 500, "declared": 10, "unknown": 0, "total": 510 },
        "gptbot":    { "verified": 200, "declared": 190, "unknown": 0, "total": 390 }
      },
      "series": [
        {
          "bucketStart": "2026-07-30",
          "bucketEnd": "2026-07-30",
          "verified": 24, "declared": 6, "unknown": 1, "total": 31
        }
      ]
    }
  ],
  "nextCursor": "eyJ2IjoxLCJkIjoiMTExMTExMTEt..."
}

Fields

Field	Type	Description
`generatedAt`	string	ISO 8601 timestamp of when the export was produced.
`period`	string \| null	The rolling period applied, or `null` for an explicit range or any cursor request.
`startDate` / `endDate`	string	Resolved window (`YYYY-MM-DD`, inclusive). `startDate` may be later than requested if the window was clamped to `legacyCutover`.
`requestedStartDate`	string	Present only when the window was clamped — your original start date.
`granularity`	string	The bucket size actually used for `series`: `day` or `week`.
`userId`	string	The account that owns the API key.
`legacyCutover`	string	First date with page-level data (`2026-07-09`).
`domain` / `domainId` / `role`	string	The exported domain and your access level (`owner`, `manager`, `viewer`).
`pageCount`	number	Total distinct paths matching the window and filters — across all pages of results, not just this one.
`pages[].path`	string	The crawled path.
`pages[].total`	number	Total crawls of this path in the window (after filters).
`pages[].tiers`	object	The path’s `verified` / `declared` / `unknown` split.
`pages[].bots`	object	Per-bot window aggregate for this path, each with its own tier split and `total`.
`pages[].series`	array	Bucketed time series (omitted when `series: false`). Each entry has `bucketStart`/`bucketEnd` plus either the tier counts, or — when a `botId` filter is active — a tier object under each bot key.
`overflow`	object	Crawls recorded against the synthetic `__overflow__` path (created when a domain-day exceeds the per-day path cap at ingest), with its own `verified` / `declared` / `unknown` / `total`. Reported separately so it never appears in the ranked list. Omitted entirely when there is none.
`nextCursor`	string \| null	Pass as `cursor` to fetch the next page. `null` on the last page.

Buckets are anchored to your window, not the calendar. With week granularity, buckets advance in 7-day steps from startDate, so the first and last bucket may be partial — check bucketStart/bucketEnd rather than assuming full weeks. Aggregates (total, tiers, bots) are always exact window sums regardless of granularity.

The cursor pins the resolved window, so paging through results at midnight won’t shift the data between pages — page 2 always matches the window page 1 was computed from.

Error Responses

Status	Body	Description
400	`{ "error": "invalid_request", "message": "..." }`	Missing `domainId`; an invalid window, `granularity`, `sortBy`, `pageSize`, `botId`, `tier`, or `pathPrefix`; `day` granularity on a window over 90 days; or a window that ends before `legacyCutover`. The `message` field explains which.
400	`{ "error": "invalid_cursor", "message": "..." }`	The `cursor` token is malformed or expired. Restart from the first page.
401	`{ "error": "invalid_api_key" }`	API key is missing, invalid, or revoked.
403	`{ "error": "plan_upgrade_required" }`	Programmatic export requires the Pro plan or above.
404	`{ "error": "domain_not_found" }`	The `domainId` doesn’t exist or isn’t accessible to your account.
429	`{ "error": "rate_limit_exceeded", "usage": 300, "limit": 300 }`	Monthly or per-minute rate limit exceeded.

Examples

Paging through every crawled page

async function fetchAllPages(domainId) {
  const url = "https://api.hadoseo.com/functions/v1/export-page-analytics";
  const headers = {
    "Authorization": `Bearer ${process.env.HADOSEO_API_KEY}`,
    "Content-Type": "application/json",
  };

  const pages = [];
  let body = { domainId, period: "30d", series: false };
  while (true) {
    const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
    if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
    const data = await res.json();
    pages.push(...data.pages);
    if (!data.nextCursor) return pages;
    body = { cursor: data.nextCursor, series: false };
  }
}

Each API request counts against your monthly quota, so prefer a larger pageSize (up to 500) over many small pages when exporting a whole domain — and set series: false if you only need the aggregates.

Overview

Endpoints

Export Page Analytics

Request

Headers

Body Parameters

Example Request

Response

Success (200)

Fields

Error Responses

Examples

Paging through every crawled page

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (200)

​Fields

​Error Responses

​Examples

​Paging through every crawled page

Request

Headers

Body Parameters

Example Request

Response

Success (200)

Fields

Error Responses

Examples

Paging through every crawled page