POST /api/v1/analyze

Summary#

POST /api/v1/analyze is the only public endpoint in the Metric Vault API. It takes a domain and returns a single JSON object containing a competitive analysis: authority and SEO scores, estimated traffic, brand sentiment, market position, a content-gap score, a threat level, keywords, competitors, opportunities, weaknesses and a written summary. It requires an mv_live_ API key, the Enterprise plan, and it costs 6 credits per successful call.

Overview#

The endpoint is synchronous. One request produces one complete analysis in the response body; there is no job id, no polling and no callback. The call runs a language-model analysis inside the request, so expect several seconds of latency and set a generous client timeout.

Endpoint#

Request headers#

Request body#

Any other field in the body is ignored. An unparseable body is treated as an empty object, which then fails the missing-target check.

{ "url": "example.com" }

Response#

200 OK

{
  "ok": true,
  "url": "example.com",
  "analysis": { }
}

The analysis object#

The array lengths above are what the endpoint asks for and normally returns. Write your client so that a missing field or a differently-sized array does not throw: read defensively rather than destructuring blindly.

Errors#

Responses are JSON with an error string, and sometimes a machine-readable code. The request stops at the first gate that fails.

The 429 body also carries plan, used, quota, cost, reset_at in ISO form, reset_date in readable form, days_until_reset and upgrade_url. The full catalogue is in Error codes.

Order of checks#

The endpoint applies its gates in a fixed order, which determines what you are charged:

A 200 has always been metered. Anything else has not.

Side effects of a successful call#

Metering is best-effort in the sense that a failure to record usage does not fail your request. It does not mean calls are free.

Limits#

Example#

curl -sS -X POST https://metricvaultai.com/api/v1/analyze \
  -H "Authorization: Bearer mv_live_3f9a1c7d4b28e05a6f13c9d720b48e1a5c6d7f0293a4b1c8" \
  -H "Content-Type: application/json" \
  -d '{"url": "notion.so"}'

{
  "ok": true,
  "url": "notion.so",
  "analysis": {
    "domainAuthority": 86,
    "seoScore": 81,
    "estimatedTraffic": "9.4M/mo",
    "brandSentiment": "Positive",
    "sentimentScore": 84,
    "marketPosition": "Leading all-in-one workspace for teams and individuals",
    "contentGapScore": 46,
    "threatLevel": "Medium",
    "topKeywords": ["notion templates", "note taking app", "project management tool", "wiki software", "notion ai"],
    "competitors": ["coda.io", "clickup.com", "obsidian.md"],
    "opportunities": ["Template-led landing pages for niche workflows", "Comparison content against task-first competitors"],
    "weaknesses": ["Limited depth on enterprise governance queries", "Community content outranks owned pages on how-to intent"],
    "summary": "Notion converts strong branded demand into broad category visibility, with template and how-to queries driving most non-branded entry. The largest gap is owned depth on workflows where community content currently ranks first."
  }
}

More languages are in Code examples.

Screenshots#