---
title: "Analyze content optimization score"
method: POST
path: "/api/v1/score"
tags: ["v1", "Guide"]
---

# Analyze content optimization score

`POST /api/v1/score`

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

Analyzes the optimization score of the provided content for a specific guide

## Request body

- object
  - `guideId` string, required: ID of the guide to analyze
  - `content` string, required: Content to analyze
  - `pageUrl` string: Optional. Read only for a visitor of a guide shared in read-only mode: the URL of one of the guide's SERP pages, whose stored content is then analysed instead of the guide's text. Ignored for the owner and for a guide shared in edit mode. Unknown URL: the guide's text is analysed.
  - `saveToGuide` boolean: Whether to save the content and the analysis score back to the guide (default: true)
  - `scoreProgressive` boolean: Whether to compute the progressive score build-up curve (default: true). When false, progressiveScores is returned empty. Null is treated as "not provided", so the default applies.
  - `includeEmbedding` boolean: Whether to compute the semantic embedding analysis, i.e. proximity and PCA (default: true). When false, the embeddingAnalysis key is omitted from the response. Null is treated as "not provided", so the default applies.

## Response `200`

Successful response with content analysis results. A call that saves nothing (`saveToGuide: false`, or a guide shared in read-only mode) and that repeats an identical request made less than 10 minutes ago is served from a cache, with the same body and without a new analysis.

- object
  - `success` boolean
  - `guide` object
    - `id` string
    - `query` string
    - `lang` string
    - `userId` string
  - `contentAnalysis` object
    - `structure` object
      - `length` number
      - `headings` number
      - `paragraphs` number
      - `images` number
      - `videos` number
      - `links` number
      - `tables` number
      - `lists` number
    - `expressions` object
    - `score` number

## Other responses

- `400`: Bad request (missing guide ID or content)
- `401`: Unauthorized
- `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. Nothing is analysed, nothing is saved and nothing is charged.
- `429`: Too many score requests: at most 60 calls per UTC minute and per account, calls served from the cache included (without an account, per guide). Nothing is analysed and nothing is saved. Wait the number of seconds given by `Retry-After` (also `retryAfter` in the body) before calling again: earlier calls are refused the same way. Repeating an unchanged request is not needed, an identical result stays available from the cache for 10 minutes.
- `500`: Server error

---

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