Export Analytics - Hado SEO

POST /functions/v1/export-user-analytics

Returns a single JSON document with report-style analytics for every domain on your account — both domains you own and domains shared with you. Unlike the dashboard charts and PDF report, which group smaller crawlers into “Other” and “Other social”, this endpoint breaks traffic out into each individual bot.

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. The Export all (JSON) button in the Analytics dashboard is available on all plans.

Request

Headers

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

Body Parameters

Choose the reporting window in one of two ways — a rolling period, or an explicit startDate/endDate range. The two are mutually exclusive.

Parameter	Type	Required	Description
`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`.
`domainId`	string	No	Restrict the export to a single domain by its ID. Omit to export every domain your account can access (the default). Get IDs from List Domains.

The window applies to every domain in the response. By default the export covers every domain your account can access; pass domainId to scope it to one.

Exporting one domain at a time with domainId (optionally with a narrower date range) is the way to handle large or old domains: a single heavy domain can otherwise time out the whole account-wide export. Use List Domains to enumerate IDs, then export each.

Fetching non-overlapping reports. Use startDate/endDate to page through history in adjacent, gap-free chunks (e.g. one month at a time) without double-counting. The response echoes back the resolved startDate and endDate, so your next request can start the day after the previous endDate. Both bounds are inclusive, so advance by one day to avoid overlap.

Range rules — a request that breaks any of these returns 400 invalid_request:

period and startDate/endDate cannot be combined.
endDate cannot be sent on its own — it requires a startDate.
Dates must be real calendar dates in YYYY-MM-DD form (e.g. 2026-02-30 is rejected).
startDate must not be after endDate, and neither may be in the future.
The range may span at most 365 days (inclusive), the same cap as the 365d period.

Example Request

Rolling period:

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

Explicit date range:

curl -X POST https://api.hadoseo.com/functions/v1/export-user-analytics \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-06-01",
    "endDate": "2026-06-30"
  }'

Single domain:

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

Response

Success (200)

{
  "generatedAt": "2026-06-29T12:00:00.000Z",
  "period": "30d",
  "startDate": "2026-05-31",
  "endDate": "2026-06-29",
  "userId": "00000000-0000-0000-0000-000000000000",
  "domainCount": 1,
  "domains": [
    {
      "domain": "example.com",
      "domainId": "11111111-1111-1111-1111-111111111111",
      "role": "owner",
      "summary": {
        "totalCrawls": 1840,
        "prerenders": 412,
        "cachedViews": 1520,
        "cacheMisses": 320,
        "cacheHitRate": 82.6
      },
      "botTotals": {
        "googlebot": 920,
        "googleextendedbot": 14,
        "bingbot": 210,
        "openaibot": 88,
        "anthropicbot": 31,
        "perplexitybot": 12,
        "twitterbot": 40,
        "facebookbot": 35,
        "linkedinbot": 22,
        "slackbot": 9,
        "discordbot": 4,
        "whatsappbot": 6,
        "telegrambot": 3,
        "pinterestbot": 2,
        "snapchatbot": 0,
        "redditbot": 5,
        "metabot": 7,
        "quorabot": 1,
        "social_other": 8,
        "applebot": 18,
        "amazonbot": 11,
        "baidubot": 6,
        "yandexbot": 9,
        "duckduckbot": 4,
        "bytespiderbot": 25
      },
      "botSeries": [
        { "date": "2026-06-28", "googlebot": 41, "bingbot": 9, "openaibot": 3, "bytespiderbot": 1 }
      ],
      "topPages": [
        {
          "url": "https://example.com/blog/launch",
          "seoScore": 92,
          "seoIssuesCount": 1,
          "botTotal": 134
        }
      ],
      "seo": {
        "good": 120,
        "needsWork": 18,
        "poor": 4,
        "unknown": 9,
        "totalPages": 151,
        "totalIssues": 47
      }
    }
  ]
}

Each botSeries entry contains a count for every bot listed in botTotals. The example above is trimmed to a few bots for brevity; the actual response includes all of them, with 0 where there was no traffic.

Fields

Field	Type	Description
`generatedAt`	string	ISO 8601 timestamp of when the export was produced.
`period`	string \| null	The rolling period applied (`1d`, `7d`, `30d`, `90d`, `365d`), or `null` when an explicit `startDate`/`endDate` range was requested.
`startDate`	string	Resolved start of the window (`YYYY-MM-DD`, inclusive).
`endDate`	string	Resolved end of the window (`YYYY-MM-DD`, inclusive).
`userId`	string	The account that owns the API key.
`domainCount`	number	Number of domains included.
`domains[].domain`	string	The domain name.
`domains[].domainId`	string	The domain’s unique ID.
`domains[].role`	string	Access level for this domain: `owner`, `manager`, or `viewer`.
`domains[].summary`	object	Period totals: `totalCrawls`, `prerenders`, `cachedViews`, `cacheMisses`, `cacheHitRate`.
`domains[].botTotals`	object	Total visits per individual bot for the period.
`domains[].botSeries`	array	Per-day breakdown; each entry has a `date` plus a count for every bot.
`domains[].topPages`	array	Top pages by bot traffic: `url`, `seoScore`, `seoIssuesCount`, `botTotal`.
`domains[].seo`	object	SEO health bucket counts (`good`, `needsWork`, `poor`, `unknown`) plus `totalPages` and `totalIssues`.

Granular bot breakdown

Every bot is reported as its own field. The bots that the dashboard and PDF report fold into “Other” and “Other social” each appear individually here:

Bucket in reports	Individual bots in `botTotals` / `botSeries`
Other social	`slackbot`, `discordbot`, `whatsappbot`, `telegrambot`, `pinterestbot`, `snapchatbot`, `redditbot`, `metabot`, `quorabot`, `social_other`
Other	`applebot`, `amazonbot`, `baidubot`, `yandexbot`, `duckduckbot`, `bytespiderbot`

The named bots already shown in reports are also present individually: googlebot, googleextendedbot, bingbot, openaibot, anthropicbot, perplexitybot, twitterbot, facebookbot, and linkedinbot.

social_other is a catch-all for social crawlers that can’t be identified individually. It’s reported as its own field rather than merged into another bot.

Error Responses

Status	Body	Description
400	`{ "error": "invalid_request", "message": "..." }`	Invalid `period`; a malformed, out-of-order, or future date; a range over 365 days; `period` combined with a date range; or `endDate` without `startDate`. The `message` field explains which.
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

When you receive a 429, the usage and limit fields tell you where you stand against your monthly quota. Per-minute limits (60 req/min) reset automatically after 60 seconds. See Authentication for plan limits.

Examples

JavaScript / Node.js

const response = await fetch(
  "https://api.hadoseo.com/functions/v1/export-user-analytics",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.HADOSEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ period: "30d" }),
  },
);

const report = await response.json();
for (const domain of report.domains) {
  console.log(domain.domain, domain.botTotals);
}

Paging through history without overlap

Because both bounds are inclusive, start each window the day after the previous endDate to fetch adjacent, gap-free chunks:

async function fetchWindow(startDate, endDate) {
  const res = await fetch(
    "https://api.hadoseo.com/functions/v1/export-user-analytics",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.HADOSEO_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ startDate, endDate }),
    },
  );
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).message}`);
  return res.json();
}

// Two back-to-back months — no overlapping days.
const june = await fetchWindow("2026-06-01", "2026-06-30");
const july = await fetchWindow("2026-07-01", "2026-07-31");

Prefer a one-off download? The Analytics dashboard has an Export all (JSON) button that produces the same document for the selected period without needing an API key — and it’s available on every plan.

​Request

​Headers

​Body Parameters

​Example Request

​Response

​Success (200)

​Fields

​Granular bot breakdown

​Error Responses

​Examples

​JavaScript / Node.js

​Paging through history without overlap

Request

Headers

Body Parameters

Example Request

Response

Success (200)

Fields

Granular bot breakdown

Error Responses

Examples

JavaScript / Node.js

Paging through history without overlap