iAdvizeDocs

List a site's pages

Returns the pages of this site with the site's totals by status and type, the number of pages it holds against its limit, the generation and read budgets and its last sitemap import. The totals count every page whatever the filters. The order is newest first unless `sort` asks for another; each sort pages with its own cursor. A list never carries the extracted text: get one page for it. Filters combine with AND. `limit` is 1 to 100 (50 by default), and a cursor is bound to the filters and the sort it was issued for.

GET
/api/v1/sites/{siteId}/pages

Authorization

ApiKeyAuth
AuthorizationBearer <token>

A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).

In: header

Path Parameters

siteId*string

The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.

Query Parameters

q?string

Only pages whose address or title contains this text, ignoring case.

Lengthlength <= 200
type?string

Only pages of this type. A page not read yet matches on the type guessed from its address.

Value in

  • "product"
  • "category"
  • "content"
  • "blog"
  • "home"
  • "unknown"
status?string

Only pages with this status.

Value in

  • "pending"
  • "reading"
  • "read"
  • "failed"
  • "unsupported"
  • "discovered"
language?string

Only pages in this language: the language the read found, or the hint for a page not read yet. fr also matches fr-CA.

Lengthlength <= 10
source?string

Only pages added this way.

Value in

  • "manual"
  • "sitemap"
  • "tag"
missingFromSitemap?boolean

true for pages a complete sitemap import no longer listed, false for the others.

sort?string

newest (the default), most_viewed (views over the last 30 days, ties oldest first), address, or last_read (never-read pages last).

Default"newest"

Value in

  • "newest"
  • "most_viewed"
  • "address"
  • "last_read"
order?string

The direction of sort: asc or desc. Absent, each sort keeps its own: address ascending, the others descending (newest, most viewed and last read first). most_viewed ascending breaks ties newest first. last_read lists never-read pages last in both directions. A cursor only continues the sort and direction it was issued for.

Value in

  • "asc"
  • "desc"
startersGenerated?boolean

true for pages that produced at least one question, false for pages that produced none.

starters?string

with for pages that have generated questions, none for pages that have none, generating for pages whose generation is in progress. The three are exclusive: a page being generated is listed only under generating. startersGenerated is the older boolean and does not leave pages in progress out.

Value in

  • "with"
  • "none"
  • "generating"
lastGeneration?string

Only pages whose latest generation ended this way.

Value in

  • "written"
  • "none_passed"
  • "skipped"
  • "failed"
  • "read"
  • "unsupported"
cursor?string

The meta.nextCursor of the previous page, with the same filters and sort.

Lengthlength <= 4096
limit?integer

The page size, 1 to 100.

Range1 <= value <= 100
Default50

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/api/v1/sites/string/pages"
{  "data": [    {      "id": "spg_01kvnwmagvf27rc9cze5rm9e1r",      "url": "https://shop.example/products/trail-shoe",      "finalUrl": null,      "source": "manual",      "pageType": "product",      "status": "read",      "reason": null,      "language": "en",      "title": "Trail shoe",      "lastReadAt": "2026-10-03T08:59:00.000Z",      "createdAt": "2026-10-03T08:58:00.000Z",      "updatedAt": "2026-10-03T08:59:00.000Z",      "starterQuestionCount": 3,      "lastGeneration": {        "id": "spgr_01kvnwmagvf27rc9cze5rm9e1r",        "trigger": "requested",        "outcome": "written",        "reason": null,        "catalogReason": null,        "catalogRecordTitle": "Trail shoe",        "catalogRecordId": "gid://shopify/Product/8123",        "candidates": 6,        "questionsWritten": 3,        "createdAt": "2026-10-03T09:00:00.000Z",        "finishedAt": "2026-10-03T09:00:12.000Z"      },      "languageHint": null,      "pageTypeGuessed": false,      "pageTypeSource": "structured_data",      "pageTypeConfidence": "likely",      "canonicalUrl": null,      "duplicateOfPageId": null,      "views30d": 128,      "views30dAt": "2026-10-03T03:00:00.000Z",      "lastmod": null,      "lastSeenInSitemapAt": null,      "missingFromSitemapSince": null    }  ],  "meta": {    "nextCursor": null,    "totals": {      "total": 1,      "byStatus": {        "pending": 0,        "reading": 0,        "read": 1,        "failed": 0,        "unsupported": 0,        "discovered": 0      },      "byType": {        "product": 1,        "category": 0,        "content": 0,        "blog": 0,        "home": 0,        "unknown": 0      }    },    "generationBudget": {      "limit": 12500,      "used": 3,      "remaining": 12497,      "resetsAt": "2026-10-04T00:00:00.000Z"    },    "readBudget": {      "limit": 25000,      "used": 12,      "remaining": 24988,      "resetsAt": "2026-10-04T00:00:00.000Z"    },    "pageCount": 1,    "pageLimit": 50000,    "lastImport": {      "id": "spgi_01kvnwmagvf27rc9cze5rm9e1r",      "state": "completed",      "outcome": "completed",      "startedBy": "api",      "sitemapGiven": false,      "counts": {        "sitemapSource": "robots",        "documentsRead": 5,        "documentsFailed": {          "address_not_allowed": 0,          "not_on_site": 0,          "redirected_off_site": 0,          "too_many_redirects": 0,          "not_found": 0,          "http_error": 0,          "timed_out": 1,          "unreachable": 0,          "not_a_sitemap": 0,          "unreadable": 0        },        "found": 1240,        "created": 1180,        "alreadyHeld": 52,        "excluded": 6,        "refused": {          "not_a_valid_address": 0,          "contains_wildcard": 0,          "not_on_site": 2,          "too_long": 0,          "not_a_page": 0        },        "overCap": 0,        "createdByType": [          {            "key": "product",            "count": 940          },          {            "key": "category",            "count": 180          },          {            "key": "blog",            "count": 60          }        ],        "createdByTypeRest": 0,        "createdByLanguageHint": [          {            "key": null,            "count": 700          },          {            "key": "fr",            "count": 480          }        ],        "createdByLanguageHintRest": 0      },      "boundsReached": [],      "startedAt": "2026-10-03T08:00:00.000Z",      "endedAt": "2026-10-03T08:03:10.000Z"    }  }}

Rename a version

Names a version of the agent, as Rename does in the dashboard. A name is a label, not configuration: no saved state changes, and a locked version (one that has been live or is part of an A/B test) can be renamed too. `null` or an empty name clears it, so the version reads as `V` followed by its number again. The version is the `lineId` of its saved states.

Add pages

Judges a list of addresses and, unless `dryRun` is true, adds the accepted ones as pages and starts reading them in the background. The rules are the dashboard's: a path is resolved against the site's URL; a full address must be http or https and on the site's own origin (the origin of its URL or an allowed origin). An http address is upgraded to https, and a host that differs from an exactly allowed origin only by a leading `www.` is rewritten to it. The address is then normalized: the fragment, every `utm_` parameter, the click identifiers `gclid`, `gbraid`, `wbraid`, `dclid`, `fbclid`, `msclkid`, `ttclid`, `twclid`, `li_fat_id`, `igshid`, `yclid`, `srsltid`, `mc_cid`, `mc_eid`, `_ga`, `_gl` and `_kx`, and a trailing slash on a path other than `/` are removed; other query parameters are kept as written, in order. A repeat is ignored, and above 50 non-empty lines the whole request is refused with `invalid_request` and nothing is created. The answer names the outcome of every line. The answer is `202` when a read was started: read the progress from the pages. It is `200` for a dry run, and when no line was accepted.