create_editorial_velocity_comparison
create_editorial_velocity_comparisonCompare 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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Market of the keyword, a code such as fr-fr, en-us, en-gb, de-de, es-es, it-it. | |
| sites | No | Host names or URLs of the sites to compare. Reduced to their host, subdomain kept, www removed, duplicates removed. 2 to 11 distinct sites, ownSite included. Do not send with keyword. | |
| keyword | No | A search query. The distinct sites of its Google organic top 10 are compared. Requires lang. Do not send with sites. | |
| ownSite | No | Optional. Host name or URL of your own site. Analysed and shown apart, never part of the median. With keyword, it adds one place to the maximum charged. |