---
title: "Get data for a specific guide"
method: GET
path: "/api/v1/guide"
tags: ["v1", "Guide"]
---

# Get data for a specific guide

`GET /api/v1/guide`

## Request

- Base URL: `https://app.serpmantics.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.serpmantics.com/api/v1/guide`
- Auth: HTTP bearer

Retrieves details of a specific guide. While the guide is being created, the endpoint returns 202 (poll again later). If the creation failed permanently (explicit terminal flag, or a failure older than 15 minutes with no retry left, see progressStatus.terminalInferred), it returns 200 with success=false, status=failed, a human-readable French error message, creationFailed=true, refunded (whether the consumed credits were automatically given back) and guide.progressStatus (raw reason, message, terminal, kind, and failureFacts when the figures are known, which is only possible for sources whose web pages we read, that is a search engine or a `_CITATIONS` source, never a source in answer mode). Stop polling in that case.

## Query parameters

- `id` string, required

## Response `200`

Guide successfully retrieved, or guide creation failed permanently (success=false, status=failed)

- union
  - object: Guide ready
    - `success` boolean
    - `guide` object
      - `id` string
      - `query` string
      - `lang` string
      - `source` string: Engine and analysis mode the guide targets, returned as the UPPERCASE database form of the source (e.g. `GOOGLE`, `CHATGPT`, `CHATGPT_CITATIONS`, `GOOGLE_AI_OVERVIEW`, `GOOGLE_AI_OVERVIEW_CITATIONS`). Either the Google SERP (`GOOGLE`), Google's AI answers as `GOOGLE_AI_OVERVIEW` (answer text analysis) or `GOOGLE_AI_OVERVIEW_CITATIONS` (analysis of the cited sources), or an AI engine as `<ENGINE>` (AI answer analysis) or `<ENGINE>_CITATIONS` (analysis of the sources the AI cites)
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `shareState` 'private' | 'shared-read' | 'shared-edit': Sharing mode of the guide. Always returned, and `private` when the guide has never been shared. Change it with PUT /api/v1/guide.
      - `shareUrl` string, uri, nullable: Public URL of the guide, readable without an account, returned when `shareState` starts with `shared-`. `null` when the guide is private (or when the server has no public URL configured).
      - `guide` object
        - `structure` object
          - `length` object
            - `from` number
            - `to` number
          - `headings` object
            - `from` number
            - `to` number
          - `paragraphs` object
            - `from` number
            - `to` number
          - `images` object
            - `from` number
            - `to` number
          - `videos` object
            - `from` number
            - `to` number
          - `linksInternal` object
            - `from` number
            - `to` number
          - `linksExternal` object
            - `from` number
            - `to` number
          - `tables` object
            - `from` number
            - `to` number
          - `lists` object
            - `from` number
            - `to` number
        - `add` object[]
          - `expression` string
          - `from` number
          - `to` number
          - `isStatisticallyDifferent` boolean
          - `serpResultsPresence` object
        - `avoid` object[]
          - `expression` string
          - `serpResultsPresence` object
      - `scoreGuidelines` object
        - `expressions` object
          - `bad` number
          - `poor` number
          - `good` number
          - `supreme` number
        - `stats` object
          - `expressionsAddOptimisation` object
            - `isStatisticallyDifferent` boolean
            - `lowerWhisker` number
            - `q25` number
            - `median` number
            - `q75` number
            - `upperWhisker` number
          - `structureOptimisation` object
            - `isStatisticallyDifferent` boolean
            - `lowerWhisker` number
            - `q25` number
            - `median` number
            - `q75` number
            - `upperWhisker` number
      - `topSERPResultsDetails` unknown[]
        - unknown
      - `isReady` boolean
      - `corpusTopWindow` GuideCorpusTopWindow: Present ONLY on a guide built from pages ranked beyond the top 10 (shared by /guide and /guides). None of the first 10 results of the search engine could be kept for the analysis, so the guide relies on the next ranked pages instead of failing. Absent on every other guide, which is the normal case: treat a missing field as "built on the top 10". Positions are the real ranks, never renumbered.
        - `fallback` boolean: Always `true` when the object is present.
        - `maxPosition` integer: Rank of the last page the guide relies on (30 at most).
        - `documents` integer: Number of pages the guide relies on.
      - `serpQuestions` object[], nullable: People also ask questions that Google shows below the first results for the query, in SERP order. Always present. `null` for a guide created before 2026-10-19 (the field did not exist yet), `[]` when the SERP showed no such block. Only the questions are returned, never Google's answers.
        - `position` integer, nullable, required: Absolute rank of the questions block among the SERP items (the same for every question of one block), or `null` when unknown.
        - `question` string, required: The question as Google displays it, plain text.
        - `seedQuestion` string, nullable, required: Question this one was expanded from, or `null` for a top-level question.
  - object: Guide creation failed permanently (stop polling). `status` is `failed`, `error` holds the human-readable French message and `guide.progressStatus` exposes the raw `reason`, the `message`, `terminal`, `kind` (`legitimate` or `technical`) and, when the figures are known, `failureFacts` (only for sources whose web pages we read, that is a search engine or a `_CITATIONS` source, never a source in answer mode).
    - `success` boolean
    - `status` 'failed'
    - `error` string: Human-readable French message explaining the failure (depends on the reason and the source)
    - `creationFailed` boolean
    - `refunded` boolean: Whether the consumed credits were automatically given back (refund journaled in the credits ledger)
    - `guide` object
      - `id` string
      - `query` string
      - `lang` string
      - `source` string
      - `progressStatus` GuideProgressStatus: Creation progress of a guide (shared by /guide and /guides). When `step` is `failed`, `generationFailed`, `terminal`, `reason`, `message` and `kind` are set, and `failureFacts` may be (only for sources whose web pages we read).
        - `isReady` boolean: True once the guide is ready to be read
        - `pct` number: Creation progress in percent (0 to 100)
        - `step` 'notStarted' | 'queued' | 'created' | 'serpFetched' | 'pagesCrawled' | 'ready' | 'failed': Current creation step. `queued` (returned by GET /api/v1/guides, and by the 202 of GET /api/v1/guide): the guide has not started and is held because the account is beyond the priority guides of its plan for the current month; held guides start at a rate of one per hour, in creation order. See `estimatedStartAt`.
        - `estimatedStartAt` string, date-time: Only when step is `queued`. Estimated start of the generation (UTC). An estimate, not a promise: the guide then moves to `created` and the usual steps.
        - `upgradeUrl` string: Only when step is `queued`, and only when the "Priority and API volume" add-on can raise this account's monthly volume. Absolute URL where to buy it.
        - `requiresValidation` boolean: Present and true when the guide waits for the user to validate the results to analyse
        - `generationFailed` boolean: Present and true when the creation failed (step `failed`)
        - `terminal` boolean: Only when step is `failed`. True when the failure is definitive (explicit backend flag, or inferred when the failure is older than 15 minutes, see `terminalInferred`). False while the backend may still retry (failure younger than 15 minutes without the explicit flag).
        - `terminalInferred` boolean: Only when step is `failed` and `terminal` is true without the explicit backend flag (failure older than 15 minutes, no retry will happen). Present and true in that case only. The refund status is then given by the `refunded` field of /guide, never promised in `message`.
        - `reason` 'exception-creation' | 'no-serp-results' | 'not-enough-serp-results' | 'not-enough-fetchable-pages' | 'no-top10-fetchable-pages' | 'failed-to-save-serp-results' | 'exception-fetch-serp' | 'exception-fetch-results' | 'exception-fetch-llm-citations' | 'no-citations' | 'unsupported-locale' | 'exception-fetch-llm-content' | 'no-ai-overview-available' | 'exception-fetch-ai-overview' | 'exception-process-corpus' | 'exception-wrap-up' | 'failed-task' | 'relaunch_count_exceeded', nullable: Only when step is `failed`. Raw, stable failure reason slug
        - `message` string: Only when step is `failed`. Human-readable French message, depending on the reason and the source of the guide
        - `kind` 'legitimate' | 'technical': Only when step is `failed`. `legitimate`: the query or the source does not allow a guide to be built (no results, too few readable pages, no AI Overview, unsupported language); nothing is broken, change the query or the source. `technical`: an error on our side, including any unknown reason.
        - `failureFacts` object: Only when step is `failed`, only for the reasons `not-enough-fetchable-pages` and `no-top10-fetchable-pages`, only for sources whose web pages we read (a search engine such as `GOOGLE` or `BING`, or a `_CITATIONS` source), and only when the figures could be read and cross-checked. Never set for a source in answer mode (`GOOGLE_AI_OVERVIEW`, `CHATGPT`, `PERPLEXITY`, ... without `_CITATIONS`): those guides are built from AI answers, no web page is read. Absent otherwise: never assume 0. Always `attempted = readable + notAnalyzable + invalidContent + unreachable`.
          - `attempted` integer, required: Number of results whose page we tried to read.
          - `readable` integer, required: Number of pages read and usable for the analysis.
          - `unreadable` object, required: Pages that could not be read, by cause.
            - `notAnalyzable` integer, required: Pages on sites we do not analyze (social networks, video platforms).
            - `invalidContent` integer, required: Pages whose content is too short or unreadable.
            - `unreachable` integer, required: Pages that are unreachable or protected.

## Other responses

- `202`: Guide is still being created (poll again later). Never returned for a permanently failed guide (see the 200 failed shape). The body is `{ success: false, error: "Guide is not ready yet" }`. When the guide is queued (the account is beyond the priority guides of its plan this month, so further guides start at a rate of one per hour), the same 202 also carries `queued: true`, `estimatedStartAt`, `startsSoon`, `message`, `upgradeUrl` (only when the "Priority and API volume" add-on can raise this account's volume) and `progressStatus` (at the root, step `queued`). There is never a `guide` key in a 202. A queued guide may wait several hours: keep polling only while `startsSoon` is true, otherwise poll less often, or come back after `estimatedStartAt`.
- `400`: Missing guide ID
- `401`: Unauthorized - User doesn't own the guide or invalid token
- `404`: Guide not found
- `410`: Guide expired. Guides are locked 180 days after their creation, because the Google results they are built on are no longer representative. The body is `{ success: false, error: "Guide expired", expiresAt: "<ISO 8601 expiry date>" }`. Definitive: do not retry, create a new guide on the same keyword. The guide is NOT deleted, it still appears in GET /api/v1/guides with `expired: true`, and DELETE /api/v1/guide still removes it.
- `500`: Server error - Failed to get guide

---

[API](https://skmtc.dev/serpmantics/apis/api-serpmantics.md) · [All operations](https://skmtc.dev/serpmantics/apis/api-serpmantics/llms.txt) · [OpenAPI document](https://skmtc.dev/serpmantics/apis/api-serpmantics/revisions/885ab1bdaa96?raw)