Compare the editorial velocity of competitors, paid in tokens (account only)
Measures how many articles each site publishes per month, for a list of sites or for the sites ranking
in the Google top 10 of a keyword, then returns the median of the competitors and a recommendation for
your own site. Each site is an editorial velocity analysis (same engine as createEditorialVelocity).
**Paid, ONLY WITH THE USER'S EXPLICIT AGREEMENT.** 20 tokens per site analysed. With `sites`, the price is
20 tokens times the number of distinct sites, your site included. With `keyword`, the number of sites is
only known once Google is read, so the maximum is charged, 5 tokens for the search results plus 20 tokens
for each of the 10 places (plus one for `ownSite`), 205 or 225 tokens, and the unused places are given back
as soon as the results are read. Before calling, tell the user the price and their token balance, and call
only after they agree. Never retry on your own after an error.
**What is given back.** The tokens of a site that cannot be measured (blocked, no sitemap, no dates,
unreachable, timeout, daily capacity reached), of a site served by an analysis of the same domain less than
7 days old or already running (nothing was read for you), of an unused place, and everything when the
search results cannot be read or the comparison cannot start. Refunds happen at the first read that sees them, whoever reads, or within the next hours if nobody
reads. `charged` in the answer is what stays charged after the refunds already made by this request.
**Asynchronous, poll the result.** This call answers HTTP 202 with a `comparisonId` and a `pollUrl`. Call
`GET /api/v1/tools/editorial-velocity/comparisons?comparisonId=...` every 15 seconds until `status` is `done`
or `failed`. Sites are analysed a few at a time, a comparison takes from a few minutes to 3 hours. MCP
clients must call the `get_editorial_velocity_comparison` tool again until the status is terminal.
**Input.** Exactly one of `sites` (2 to 11 distinct host names or URLs after normalisation, your site
included) or `keyword` with `lang` (a market code such as fr-fr, en-us, de-de, es-es, it-it). `ownSite`
is optional; it is added to the list when missing, counted once, and left out of the median.
**Errors.** 401 without an account. 402 INSUFFICIENT_TOKENS when the balance is below the price,
nothing is charged or started. 400 for an invalid body, nothing is charged. 429 RATE_LIMITED when 3
comparisons of the account are still running or 20 were started in the current UTC hour, nothing is
charged. A 503 means the comparison was
not started, and the tokens are given back (details.billing). A 502 means the analysis service did not
answer in time: the tokens are given back (details.billing), and the comparison may still have started, in
which case it is free (its comparisonId is not known, do not retry without the user). A 500 TOKENS_NOT_CONSUMED
means the outcome of the debit could not be confirmed and nothing was started; if tokens were taken, they
are given back automatically within the next hours.
**Request format.** JSON body with `Content-Type: application/json` (415 otherwise). Without an
`Authorization` header, a request sent by a web page of another site returns 403.