---
title: "Launch an information gain analysis on a guide"
method: POST
path: "/api/v1/information-gain"
tags: ["v1", "In-guide features"]
---

# Launch an information gain analysis on a guide

`POST /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.

Answers the question "what is missing from my text to bring more than the top results, and where?". The analysis reads the competing pages of the guide's Google results, extracts the facts they state (each with a verbatim excerpt), groups them, checks which ones the guide text states (covered, partial or absent), and lists information gain leads found beyond the top results plus first-hand questions only the author can answer.

When to call it. Once per guide, or again after the competing pages changed. To check an edited text against an existing analysis, call recheck_information_gain_coverage instead (about 10 seconds, no competitor is read again).

The analysis is asynchronous and takes 30 to 60 seconds. Wait about 30 seconds, then call get_information_gain (view=summary, the default) every 10 seconds until status is done or failed. Read view=summary first; ask for view=full only if the whole matrix is needed.

htmlContent is optional. When given, the guide column is checked against this HTML (send the text as displayed, without mark tags); when omitted, the text saved in the guide is used. htmlContent is limited to 2,000,000 bytes (UTF-8) through the API, and to about 1 MB through the MCP server (the size of the whole MCP request).

Costs 60 tokens, charged when the analysis is launched (202, the body carries tokensCharged). Nothing is charged when the call is refused before the launch is attempted (invalid input, 403, 404, or 409 ANALYSIS_RUNNING for an analysis already running). When the launch itself fails after the charge, whatever the status, the tokens are given back before the response and the body carries refunded (true when the credit is on the ledger, false when the refund failed and is logged for a manual replay). When an accepted analysis ends failed, its tokens are given back at the first read that sees it (get_information_gain), whose response then carries refunded and refundedTokens.

## Request body

- object
  - `guideId` string, required: ID of the guide to analyze (24 hexadecimal characters).
  - `htmlContent` string: Optional HTML of the article to check, without mark tags. Omit it to check the text saved in the guide. At most 2,000,000 bytes (UTF-8) through the API, about 1 MB through the MCP server.

## Response `202`

Analysis launched. Poll pollUrl (or call get_information_gain) until status is done or failed.

- object
  - `success` boolean
  - `data` object
    - `analysisId` string
    - `status` string
    - `pollUrl` string
    - `tokensCharged` integer: Tokens charged for this launch.

## Other responses

- `400`: Invalid input, or not enough tokens. code is INVALID_GUIDE_ID (missing or malformed guideId) or INVALID_HTML_CONTENT (htmlContent given but not a non-empty string, or not valid Unicode, for instance a lone UTF-16 surrogate), fix the input and do not retry as is. code INSUFFICIENT_TOKENS means the balance is under the 60 tokens of an analysis, nothing was charged nor launched, and the body carries inviteToUpgrade true, upgradeType tokens and tokensRequired. code TOKENS_NOT_CONSUMED means the debit could not be confirmed, nothing was launched.
- `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 nor launched. Do not retry.
- `404`: code GUIDE_NOT_FOUND. The guide does not exist, was deleted, or is not accessible to this account (owner, or guide shared for edition). The cases are deliberately indistinguishable.
- `405`: Method not allowed.
- `409`: code ANALYSIS_RUNNING. An analysis (or a recheck) is already running for this guide. The body carries analysisId (the running one, null if it could not be read) and pollUrl, so follow it instead of launching again. Nothing is charged when the running analysis is seen before charging. When it is only reported by the analysis service (concurrent launch), the tokens are given back and the body carries refunded.
- `413`: code CONTENT_TOO_LARGE. htmlContent is over 2,000,000 bytes (UTF-8). Send a shorter text, do not retry as is. A JSON body over 4 MB is refused before being read, with a plain text 413.
- `500`: Internal error. When the token debit could not be recorded, the tokens are given back and the body carries refunded.
- `502`: code BACKEND_ERROR. The analysis service did not answer or answered unexpectedly. Retry later, unless the message says retrying will not help. The tokens charged for the call are given back and the body carries refunded.
- `503`: Temporary outage (database or analysis service). Retry after a short delay.

---

[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)