---
title: "Get the latest information gain analysis of a guide"
method: GET
path: "/api/v1/information-gain"
tags: ["v1", "In-guide features"]
---

# Get the latest information gain analysis of a guide

`GET /api/v1/information-gain`

## 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/information-gain`
- Auth: HTTP bearer

Réservé : en test, accès sur invitation. Reserved feature, in test, access by invitation. Accounts without access receive 403 FEATURE_NOT_AVAILABLE.

Returns the latest analysis of the guide, whatever its status. While status is pending or running, call again every 10 seconds (an analysis takes 2 to 4 minutes, the top pages and the guide being read sentence by sentence; a recheck is usually under 30 seconds, the guide text being read sentence by sentence again before its facts are checked).

view=summary (default, read it first) is built for an agent. score is the coverage of the consensus, from 0 to 100, or null when nothing is measurable (never 0 by default). The consensus is the facts stated by at least 2 distinct sites among the top pages (a site is a registrable domain, so two pages of the same domain or of its subdomains count as one site), and each consensus fact weighs its number of sites in the score. missing lists the consensus facts absent from the text, partial the ones stated only in part (with what is missing), both sorted by number of sites, then number of pages, then best position. single lists the facts stated by one site only and not covered (outside the score). leads are facts found beyond the top results, questions are first-hand questions only the author can answer. covered lists the consensus facts the text already states, and unknown the consensus facts with no verdict on the text yet (outside the score). sites lists the distinct sites among the top pages read, one per site with its best ranked page (url, position) and its number of pages read, sorted by position. Each source carries the key of its site, the same as in sites, so a fact can be laid out site by site. counts has one scope, the consensus (consensus, covered, partial, missing, unknown), plus single, the length of the single list. Only the pages read from the top results count as pages or sites of a fact. Every fact carries pages and pagesTotal (pages that state it, pages read), sites and sitesTotal (distinct sites that state it, distinct sites among the pages read), its sources, one per page (url, position, verbatim excerpt), and the verdict on the guide text (status, excerpt, missing). Every fact also carries scoreGain, the points the score would gain if the text fully stated it, all else being equal, max(1, round(100 x sites x (1 - c) / total)), c being 0 for absent and 0.5 for partial, total the sum of sites of the consensus facts with a known verdict (the denominator of score). scoreGain is null for any other fact (covered, unknown, outside the consensus), never 0, and since every positive gain counts at least 1, the gains may add up to more than 100 minus score, so never sum them. textSource is request as soon as SERPmantics sent the text to check (htmlContent, or the saved text read when the call was made), saved when the analysis service read the saved text itself (older analyses), and null while status is pending or running, or when a failed analysis did not record it (unknown source). textHash is the fingerprint of the text actually read. sitesRead is the number of distinct sites among the top pages read (same rule as sitesTotal), null when no top page was read. limits flags partial measures, and limits.issues lists each partial failure as a stable code (leads_untriaged, source_check_partial, cross_check_partial, questions_failed, coverage_partial, coverage_no_answer, excerpts_rejected) with failed and total when known. excerpts_rejected also carries undecided, the items the check left undecided for any reason; when it equals failed, checking again would not settle them.

view=full returns the whole normalized document (full matrix of topics, facts and sources, pages read and skipped with their reason, statistics).

Reading is free. When the analysis ended failed after being launched (or the last recheck ended without a new verdict, the analysis being done again with only its error set), the tokens charged for it are given back once, at the first read that sees it. The response then carries refunded (true when the credit is on the ledger, false when the refund failed and will be tried again at a later read) and refundedTokens, for the account that was charged. Both fields are absent when nothing was given back, or when the reader is not the charged account (the tokens still go back to it).

## Query parameters

- `guideId` string, required
- `view` 'summary' | 'full'

## Response `200`

The analysis, as a summary (view=summary) or as the full normalized document (view=full).

- object
  - `success` boolean
  - `refunded` boolean: Present only when the analysis (or its last recheck) failed after being launched and charged. true when its tokens were given back, false when the refund failed (tried again at the next read).
  - `refundedTokens` integer: Tokens given back (or to give back), present with refunded.
  - `data` object: With view=summary, the fields below. Each fact is an object with id, statement, topic, pages, pagesTotal, sites, sitesTotal, sources (one per page, url, position, excerpt, site), guide (status covered, partial, absent or unknown, excerpt, missing) and scoreGain (integer or null, the points the score would gain if the text fully stated an absent or partial consensus fact, null otherwise). The sites field of a fact is a number, per fact, counting the distinct registrable domains among its sources, and decides the consensus (at least 2 sites). Do not confuse it with the top level sites field, the list of the top sites read.
    - `analysisId` string
    - `status` 'pending' | 'running' | 'done' | 'failed'
    - `stage` string, nullable
    - `mode` 'analysis' | 'guide_coverage', nullable: Nature of the current or last run. analysis reads the top pages and builds the lists, guide_coverage only re-checks the text of the guide against the facts already extracted. null when the document does not say. Read this field, not stage, to tell a re-check apart from a full analysis passing through the guide_coverage stage.
    - `progress` object, nullable: Counter written by the current stage while the analysis runs, null when the stage writes none. done and total are integers, unit is pages (pages read during the extraction) or facts (facts processed during the grouping and the check of the text). Never an estimate.
      - `done` integer
      - `total` integer
      - `unit` 'pages' | 'facts'
    - `runStartedAt` string, nullable: Start of the current run (ISO 8601), the moment the analysis went running, else its launch. null when the document does not say.
    - `lastActivityAt` string, nullable: Last write of the analysis service (ISO 8601), updated at each stage. null when the document does not say.
    - `analyzedAt` string, nullable
    - `checkedAt` string, nullable
    - `textSource` 'request' | 'saved', nullable: request when SERPmantics sent the text to check (htmlContent, or the saved text read at call time), saved when the analysis service read the saved text itself, null while status is pending or running, or when a failed analysis did not record it.
    - `textHash` string, nullable: Fingerprint of the text actually read by the guide column.
    - `score` integer, nullable
    - `compare` object: The "you versus the top" table. rows lists the text of the guide first (kind guide, label guide, no domain nor url) then each top page read, by position. Each row carries density (per100, facts per 100 words; share, the part of the words that sit in a sentence stating a fact, from 0 to 1; words; facts), or null when the density was not measured, densityReason then saying why when known (too_short, budget, no_answer, timeout, no_language_model, no_sentence). A page with density and densityReason both null on a measured analysis was not measured on this analysis (a recheck of an older analysis measures the guide text only), launch a new analysis to measure it. consensus is said out of total, the consensus facts this text states (for the guide, the covered ones), null when the consensus is empty. questions is reserved for a later lot and is null. topMedianPer100 is the median per100 of the top pages measured, null when none is. guideSentencesNoFact lists the sentences of the guide that state no fact (sentences, total, truncated), null when not measured. measured is false on an analysis made before this measure existed, launch a new analysis to get it. Density measures writing quality, not ranking, top ranked pages can have a low density.
      - `rows` object[]
        - `kind` 'guide' | 'page'
        - `label` string
        - `domain` string, nullable
        - `url` string, nullable
        - `position` integer, nullable
        - `density` object, nullable
          - `per100` number
          - `share` number
          - `words` integer
          - `facts` integer
        - `densityReason` 'too_short' | 'budget' | 'no_answer' | 'timeout' | 'no_language_model' | 'no_sentence', nullable
        - `consensus` object, nullable
          - `said` integer
          - `total` integer
        - `questions` object, nullable
      - `topMedianPer100` number, nullable
      - `guideSentencesNoFact` object, nullable
        - `sentences` string[]
        - `total` integer
        - `truncated` boolean
      - `measured` boolean
    - `counts` object: One scope, the consensus (facts stated by at least 2 distinct sites among the pages read from the top results), so consensus equals covered plus partial plus missing plus unknown. single is the length of the single list, outside the score.
      - `consensus` integer
      - `covered` integer
      - `partial` integer
      - `missing` integer
      - `unknown` integer
      - `single` integer
      - `leads` integer
      - `questions` integer
    - `missing` object[]
      - `scoreGain` integer, nullable
    - `partial` object[]
      - `scoreGain` integer, nullable
    - `single` object[]
    - `leads` object[]
    - `questions` object[]
      - `question` string
      - `why` string
    - `covered` object[]
    - `unknown` object[]: Consensus facts with no verdict on the guide text yet, sorted like missing. Its length equals counts.unknown. Outside the score.
    - `sites` object[]: The list of the top sites read (not the number of sites of a fact), one entry per distinct site (registrable domain) among the top pages read, sorted by position of its best ranked page, unknown positions last. Its length equals sitesRead, and it is empty when sitesRead is null. The site key is the one carried by each source of a fact.
      - `site` string: Key of the site, the same as the site of a source.
      - `domain` string: Host name of the best ranked page of the site, for display.
      - `url` string: URL of the best ranked page of the site.
      - `position` integer, nullable: Position of the best ranked page of the site.
      - `pages` integer: Number of top pages read from this site.
    - `sitesRead` integer, nullable: Distinct sites (registrable domains) among the top pages read, null when no top page was read. Never 0 by default.
    - `limits` object
      - `issues` object[]: Partial failures of the analysis, one entry per problem, as stable codes. A failure of the check of the guide text appears once, as coverage_partial or coverage_no_answer.
        - `code` 'leads_untriaged' | 'source_check_partial' | 'cross_check_partial' | 'questions_failed' | 'coverage_partial' | 'coverage_no_answer' | 'excerpts_rejected'
        - `failed` integer
        - `total` integer
        - `undecided` integer
    - `error` object, nullable

## Other responses

- `400`: Invalid input. code is INVALID_GUIDE_ID or INVALID_VIEW (view other than summary or full).
- `401`: Unauthorized, invalid or missing API key.
- `403`: code FEATURE_NOT_AVAILABLE. The feature is in test and reserved to invited accounts. Nothing was read. Do not retry.
- `404`: code GUIDE_NOT_FOUND (guide unknown, deleted or not accessible, deliberately indistinguishable) or NO_ANALYSIS (the guide has no analysis yet, launch one with create_information_gain).
- `405`: Method not allowed.
- `500`: Internal error.
- `502`: code BACKEND_ERROR. The analysis service did not answer or answered unexpectedly. Retry later.
- `503`: Temporary outage (database or analysis service). Retry after a short delay.

## Changes

- **2026-10-20** `e71b28ef35a8`: 1 info
  - added the optional property `data/compare` to the response with the `200` status

[Operation history](https://skmtc.dev/serpmantics/apis/api-serpmantics/changes/api/v1/information-gain/get.md)

---

[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/e71b28ef35a8?raw)