@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/seo.md

@@ -0,0 +1,660 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.seo`: SEO
+
+11 operations (5 read, 2 write, 4 billable).
+
+No hand-written client covers this area. Call it through `g8.api.seo.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [seo.d.ts](seo.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getSeoAudit`](#op-getseoaudit) | `GET /api/v1/seo/audits/{audit_id}` | read | `intent:read` | Get Seo Audit |
+| [`getSeoAuditIssues`](#op-getseoauditissues) | `GET /api/v1/seo/audits/{audit_id}/issues` | read | `intent:read` | Get Seo Audit Issues |
+| [`getSeoDomainBacklinks`](#op-getseodomainbacklinks) | `GET /api/v1/seo/domains/{domain}/backlinks` | billable | `intent:run` | Get Seo Domain Backlinks |
+| [`getSeoDomainOverview`](#op-getseodomainoverview) | `GET /api/v1/seo/domains/{domain}/overview` | billable | `intent:run` | Get Seo Domain Overview |
+| [`getSeoRankHistory`](#op-getseorankhistory) | `GET /api/v1/seo/rank-tracking/{keyword_id}/history` | read | `intent:read` | Get Seo Rank History |
+| [`listSeoAudits`](#op-listseoaudits) | `GET /api/v1/seo/audits` | read | `intent:read` | List Seo Audits |
+| [`listSeoTrackedKeywords`](#op-listseotrackedkeywords) | `GET /api/v1/seo/rank-tracking` | read | `intent:read` | List Seo Tracked Keywords |
+| [`removeSeoTrackedKeywords`](#op-removeseotrackedkeywords) | `POST /api/v1/seo/rank-tracking/keywords/remove` | write | `intent:write` | Remove Seo Tracked Keywords |
+| [`researchSeoKeywords`](#op-researchseokeywords) | `POST /api/v1/seo/keywords/research` | billable | `intent:run` | Research Seo Keywords |
+| [`saveSeoTrackedKeywords`](#op-saveseotrackedkeywords) | `POST /api/v1/seo/rank-tracking/keywords` | write | `intent:write` | Save Seo Tracked Keywords |
+| [`startSeoAudit`](#op-startseoaudit) | `POST /api/v1/seo/audits` | billable | `intent:run` | Start Seo Audit |
+
+---
+
+<a id="op-getseoaudit"></a>
+
+### `g8.api.seo.getSeoAudit(input)`
+
+**Get Seo Audit**
+
+- HTTP: `GET /api/v1/seo/audits/{audit_id}`
+- operationId: `get_seo_audit_seo_audits__audit_id__get` (also callable as `g8.api.call("get_seo_audit_seo_audits__audit_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. One audit, with its plain-language `state`. 404 if it is
+not this organisation's.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audit_id` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_SeoAudit_`: the envelope `{ data: SeoAudit, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAudit` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `max_pages` | `integer` | yes |  |
+| `state` | `SeoAuditState` | yes |  |
+| `status` | `string` | yes |  |
+| `completed_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `credits_charged` | `integer \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `onpage_score` | `number \| null` | no |  |
+| `pages_crawled` | `integer \| null` | no |  |
+| `summary_checks` | `Record<string, unknown>` | no | default `{}` |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoAudit({ path: { audit_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getseoauditissues"></a>
+
+### `g8.api.seo.getSeoAuditIssues(input)`
+
+**Get Seo Audit Issues**
+
+- HTTP: `GET /api/v1/seo/audits/{audit_id}/issues`
+- operationId: `get_seo_audit_issues_seo_audits__audit_id__issues_get` (also callable as `g8.api.call("get_seo_audit_issues_seo_audits__audit_id__issues_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The issues an audit found, grouped by type and severity,
+each with the URLs it affects.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audit_id` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_SeoAuditIssues_`: the envelope `{ data: SeoAuditIssues, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAuditIssues` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audit_id` | `string (uuid)` | yes |  |
+| `issues` | `Array<SeoAuditIssue>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoAuditIssues({ path: { audit_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getseodomainbacklinks"></a>
+
+### `g8.api.seo.getSeoDomainBacklinks(input)`
+
+**Get Seo Domain Backlinks**
+
+- HTTP: `GET /api/v1/seo/domains/{domain}/backlinks`
+- operationId: `get_seo_domain_backlinks_seo_domains__domain__backlinks_get` (also callable as `g8.api.call("get_seo_domain_backlinks_seo_domains__domain__backlinks_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+SPENDS CREDITS. A domain's backlink profile: authority, totals, dofollow / nofollow split.
+
+Same shape as the overview: `billable` despite being a GET, domain
+validated before the credit check, provider outage as a 502.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain` | `string` | yes | A bare domain - no scheme, no path. `www.` is stripped. |
+
+**Returns** `ApiResponse_SeoBacklinksOverview_`: the envelope `{ data: SeoBacklinksOverview, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoBacklinksOverview` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `authority_score` | `number \| null` | no |  |
+| `dofollow` | `integer \| null` | no |  |
+| `nofollow` | `integer \| null` | no |  |
+| `referring_domains` | `integer \| null` | no |  |
+| `total_backlinks` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.seo.getSeoDomainBacklinks({ path: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-getseodomainoverview"></a>
+
+### `g8.api.seo.getSeoDomainOverview(input)`
+
+**Get Seo Domain Overview**
+
+- HTTP: `GET /api/v1/seo/domains/{domain}/overview`
+- operationId: `get_seo_domain_overview_seo_domains__domain__overview_get` (also callable as `g8.api.call("get_seo_domain_overview_seo_domains__domain__overview_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+SPENDS CREDITS. A domain's organic footprint: overview, top keywords, top pages.
+
+A GET that costs money, so it is tiered `billable` rather than `read` -
+reading rank history and buying a domain report are not the same grant.
+`data_freshness` labels how old the provider's view is. The domain is
+validated first: a scheme or a path is a 422, before any credit is checked.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain` | `string` | yes | A bare domain - no scheme, no path. `www.` is stripped. |
+
+**Returns** `ApiResponse_SeoDomainOverviewResponse_`: the envelope `{ data: SeoDomainOverviewResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoDomainOverviewResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `overview` | `Record<string, unknown>` | yes |  |
+| `top_keywords` | `Array<Record<string, unknown>>` | yes |  |
+| `top_pages` | `Array<Record<string, unknown>>` | yes |  |
+| `data_freshness` | `string` | no | default `"labs-30-90d"` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.seo.getSeoDomainOverview({ path: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-getseorankhistory"></a>
+
+### `g8.api.seo.getSeoRankHistory(input)`
+
+**Get Seo Rank History**
+
+- HTTP: `GET /api/v1/seo/rank-tracking/{keyword_id}/history`
+- operationId: `get_seo_rank_history_seo_rank_tracking__keyword_id__history_get` (also callable as `g8.api.call("get_seo_rank_history_seo_rank_tracking__keyword_id__history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. One tracked keyword's rank, snapshot by snapshot.
+
+`days` bounds the window at 365. A keyword that is not this
+organisation's has no snapshots, so the answer is an empty history rather
+than a probe.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | A tracked keyword id from `GET /seo/rank-tracking`. |
+| `query.days` | `integer` | no | How far back to read snapshots. default `90` |
+
+**Returns** `ApiResponse_SeoRankHistory_`: the envelope `{ data: SeoRankHistory, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoRankHistory` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keyword_id` | `string (uuid)` | yes |  |
+| `snapshots` | `Array<SeoRankSnapshot>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoRankHistory({ path: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-listseoaudits"></a>
+
+### `g8.api.seo.listSeoAudits(input?)`
+
+**List Seo Audits**
+
+- HTTP: `GET /api/v1/seo/audits`
+- operationId: `list_seo_audits_seo_audits_get` (also callable as `g8.api.call("list_seo_audits_seo_audits_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. This organisation's audits, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | default `20` |
+
+**Returns** `ApiResponse_List_SeoAudit__`: the envelope `{ data: Array<SeoAudit>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAudit` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `max_pages` | `integer` | yes |  |
+| `state` | `SeoAuditState` | yes |  |
+| `status` | `string` | yes |  |
+| `completed_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `credits_charged` | `integer \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `onpage_score` | `number \| null` | no |  |
+| `pages_crawled` | `integer \| null` | no |  |
+| `summary_checks` | `Record<string, unknown>` | no | default `{}` |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.listSeoAudits();
+```
+
+---
+
+<a id="op-listseotrackedkeywords"></a>
+
+### `g8.api.seo.listSeoTrackedKeywords(input?)`
+
+**List Seo Tracked Keywords**
+
+- HTTP: `GET /api/v1/seo/rank-tracking`
+- operationId: `list_seo_tracked_keywords_seo_rank_tracking_get` (also callable as `g8.api.call("list_seo_tracked_keywords_seo_rank_tracking_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The keywords this organisation tracks, with their latest rank.
+
+An organisation whose SEO storage is still provisioning gets an empty
+list rather than an error, matching the app.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string \| null` | no | Only keywords tracked for this domain. |
+
+**Returns** `ApiResponse_List_SeoTrackedKeyword__`: the envelope `{ data: Array<SeoTrackedKeyword>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoTrackedKeyword` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cadence` | `string` | yes |  |
+| `domain` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `keyword` | `string` | yes |  |
+| `language_code` | `string` | yes |  |
+| `location_code` | `integer` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `latest_checked_at` | `string (date-time) \| null` | no |  |
+| `latest_rank` | `integer \| null` | no |  |
+| `latest_serp_url` | `string \| null` | no |  |
+| `search_volume` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.listSeoTrackedKeywords();
+```
+
+---
+
+<a id="op-removeseotrackedkeywords"></a>
+
+### `g8.api.seo.removeSeoTrackedKeywords(input)`
+
+**Remove Seo Tracked Keywords**
+
+- HTTP: `POST /api/v1/seo/rank-tracking/keywords/remove`
+- operationId: `remove_seo_tracked_keywords_seo_rank_tracking_keywords_remove_post` (also callable as `g8.api.call("remove_seo_tracked_keywords_seo_rank_tracking_keywords_remove_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `intent:write`
+
+SPENDS NOTHING. Stop tracking up to 100 keywords, by id.
+
+A POST rather than a DELETE because it takes a batch of ids in the body,
+the same shape the app uses. Gated on the Signals DELETE permission, as
+the app gates it. Ids that are not this organisation's are simply not
+removed, and the count says how many were.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SeoRemoveTrackedKeywordsRequest` | yes | Request body; fields below. |
+
+Body fields (`SeoRemoveTrackedKeywordsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keyword_ids` | `Array<string (uuid)>` | yes | min items 1, max items 100 |
+
+**Returns** `ApiResponse_SeoRemovedKeywords_`: the envelope `{ data: SeoRemovedKeywords, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoRemovedKeywords` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `removed` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.removeSeoTrackedKeywords({ body: { keyword_ids: ["00000000-0000-0000-0000-000000000000"] } });
+```
+
+---
+
+<a id="op-researchseokeywords"></a>
+
+### `g8.api.seo.researchSeoKeywords(input)`
+
+**Research Seo Keywords**
+
+- HTTP: `POST /api/v1/seo/keywords/research`
+- operationId: `research_seo_keywords_seo_keywords_research_post` (also callable as `g8.api.call("research_seo_keywords_seo_keywords_research_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+SPENDS CREDITS. Keyword ideas around a seed, from the paid data provider.
+
+`mode` picks the provider report: `ideas`, `related`, `suggestions`, or
+`auto` to let the app choose. Rows come back in that report's own shape.
+
+Runs the app's per-organisation provider rate limit (429 past it) and its
+fail-closed credit check (402 when the balance is exhausted) before
+anything is fetched. A provider outage is a 502 that says so.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SeoResearchKeywordsRequest` | yes | Request body; fields below. |
+
+Body fields (`SeoResearchKeywordsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.seed_keyword` | `string` | yes | min length 1, max length 500 |
+| `body.language_code` | `string` | no | default `"en"`, max length 10 |
+| `body.limit` | `integer` | no | default `150`, min 1, max 150 |
+| `body.location_code` | `integer` | no | default `2840` |
+| `body.mode` | `"auto" \| "ideas" \| "related" \| "suggestions"` | no | default `"auto"` |
+
+**Returns** `ApiResponse_SeoResearchKeywordsResponse_`: the envelope `{ data: SeoResearchKeywordsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoResearchKeywordsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keywords` | `Array<Record<string, unknown>>` | no | default `[]` |
+| `seed` | `SeoKeywordRow \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.seo.researchSeoKeywords({ body: { seed_keyword: "example" } });
+```
+
+---
+
+<a id="op-saveseotrackedkeywords"></a>
+
+### `g8.api.seo.saveSeoTrackedKeywords(input)`
+
+**Save Seo Tracked Keywords**
+
+- HTTP: `POST /api/v1/seo/rank-tracking/keywords`
+- operationId: `save_seo_tracked_keywords_seo_rank_tracking_keywords_post` (also callable as `g8.api.call("save_seo_tracked_keywords_seo_rank_tracking_keywords_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `intent:write`
+
+SPENDS NOTHING NOW. Start tracking up to 100 keywords for a domain.
+
+The rank checks themselves run in the background worker on the chosen
+`cadence`; saving enrols the organisation in that worker's tick. The
+saved rows come back with whatever the worker has already recorded.
+Duplicates of an existing keyword are refused with a 422 naming them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SeoSaveTrackedKeywordsRequest` | yes | Request body; fields below. |
+
+Body fields (`SeoSaveTrackedKeywordsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | min length 3, max length 255 |
+| `body.keywords` | `Array<SeoTrackKeywordItem>` | yes | min items 1, max items 100 |
+| `body.cadence` | `"daily" \| "weekly"` | no | default `"daily"` |
+| `body.language_code` | `string` | no | default `"en"`, max length 10 |
+| `body.location_code` | `integer` | no | default `2840` |
+
+**Returns** `ApiResponse_List_SeoTrackedKeyword__`: the envelope `{ data: Array<SeoTrackedKeyword>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoTrackedKeyword` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cadence` | `string` | yes |  |
+| `domain` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `keyword` | `string` | yes |  |
+| `language_code` | `string` | yes |  |
+| `location_code` | `integer` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `latest_checked_at` | `string (date-time) \| null` | no |  |
+| `latest_rank` | `integer \| null` | no |  |
+| `latest_serp_url` | `string \| null` | no |  |
+| `search_volume` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.saveSeoTrackedKeywords({ body: { domain: "acme.com", keywords: [{ keyword: "example" }] } });
+```
+
+---
+
+<a id="op-startseoaudit"></a>
+
+### `g8.api.seo.startSeoAudit(input)`
+
+**Start Seo Audit**
+
+- HTTP: `POST /api/v1/seo/audits`
+- operationId: `start_seo_audit_seo_audits_post` (also callable as `g8.api.call("start_seo_audit_seo_audits_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+SPENDS CREDITS. Start a site audit of up to `max_pages` pages.
+
+Credits are RESERVED up front, sized by `max_pages`, and charged as the
+crawl completes - `credits_charged` on the audit says what was. 402 when
+the balance cannot cover the reservation, 409 when an audit of this domain
+is already running, 503 when the credit service cannot take the hold.
+
+The audit runs in the background; poll `GET /seo/audits/{audit_id}` and
+read `state`, which explains where it is in plain language and whether it
+can be run again.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SeoStartAuditRequest` | yes | Request body; fields below. |
+
+Body fields (`SeoStartAuditRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | min length 3, max length 255 |
+| `body.max_pages` | `integer` | no | default `500`, min 10, max 500 |
+
+**Returns** `ApiResponse_SeoAudit_`: the envelope `{ data: SeoAudit, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAudit` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `id` | `string (uuid)` | yes |  |
+| `max_pages` | `integer` | yes |  |
+| `state` | `SeoAuditState` | yes |  |
+| `status` | `string` | yes |  |
+| `completed_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `credits_charged` | `integer \| null` | no |  |
+| `failure_reason` | `string \| null` | no |  |
+| `onpage_score` | `number \| null` | no |  |
+| `pages_crawled` | `integer \| null` | no |  |
+| `summary_checks` | `Record<string, unknown>` | no | default `{}` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.seo.startSeoAudit({ body: { domain: "acme.com" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-seoauditissue"></a>
+
+### `SeoAuditIssue`
+
+Mirrors `AuditIssueDTO`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `affected_count` | `integer` | yes |  |
+| `issue_type` | `string` | yes |  |
+| `severity` | `string` | yes |  |
+| `affected_urls` | `Array<Record<string, unknown>>` | no | default `[]` |
+
+<a id="type-seoauditstate"></a>
+
+### `SeoAuditState`
+
+Mirrors `AuditStateDTO` - the plain-language, recovery-oriented view of where an audit is, so a caller can explain the state rather than parse raw provider text.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `can_run_again` | `boolean` | yes | Whether to offer a manual 'Run a new audit' action |
+| `category` | `"queued" \| "running" \| "complete" \| "timeout" \| "provider_error" \| "credit_issue" \| "start_error" \| "failed"` | yes | Lifecycle state category driving the plain-language status + recovery UX |
+| `detail` | `string` | yes | Plain-language explanation of what happened |
+| `headline` | `string` | yes | One-line human status |
+| `is_terminal` | `boolean` | yes | No further automatic progress will happen |
+| `label` | `string` | yes | Short status chip label |
+| `recovery` | `string` | yes | Plain-language, safe next step (may be empty) |
+| `diagnostic` | `string \| null` | no | Secondary technical detail (raw provider text) |
+
+<a id="type-seokeywordrow"></a>
+
+### `SeoKeywordRow`
+
+Mirrors `KeywordRow`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keyword` | `string` | yes |  |
+| `competition` | `number` | no | default `0` |
+| `cpc` | `number` | no | default `0` |
+| `intent` | `string \| null` | no |  |
+| `keyword_difficulty` | `integer \| null` | no |  |
+| `search_volume` | `integer` | no | default `0` |
+
+<a id="type-seoranksnapshot"></a>
+
+### `SeoRankSnapshot`
+
+Mirrors `RankSnapshotDTO`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `snapshot_date` | `string (date)` | yes |  |
+| `rank` | `integer \| null` | no |  |
+| `serp_url` | `string \| null` | no |  |
+
+<a id="type-seotrackkeyworditem"></a>
+
+### `SeoTrackKeywordItem`
+
+Mirrors `TrackKeywordItem`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keyword` | `string` | yes | min length 1, max length 500 |
+| `search_volume` | `integer \| null` | no |  |