Skip to content
Metric VaultHelp Center
Open app

Using the API from Claude Code

Give an AI coding agent your API key once and it can run any of the 48 single-input tools for you in plain English, from any folder, without the dashboard.

Last updated 2026-10-29

Summary#

An AI coding agent such as Claude Code can run Metric Vault tools for you directly, from any folder on your machine, with no dashboard open. You store your API key once, paste a short instruction at the start of a session, and from then on you ask for the work in plain English. The agent reads the tool catalog, picks the right tool and fills it in.

There are 48 tools it can reach, covering keyword research, domain and competitor analysis, backlinks, brand and AI visibility, content briefs, the technical page checks and the responsiveness check. You never need to learn a tool name.

Purpose#

The dashboard assumes a person at a keyboard, choosing a tool and typing into it. That is the wrong shape for a question like "find the ten best keywords for this product, then write me a brief for the strongest one", which is three tools and a judgement call in the middle.

An agent handles exactly that. The reason it works reliably is that every tool in the catalog takes one value: a keyword, a domain, a brand, a topic or a page URL. There is no second field for the agent to guess wrong about, which is why these particular tools are the ones exposed. See Tool endpoints for the endpoints themselves.

Requirements#

  • An Enterprise plan. The plan is re-checked on every call, so a key stops working the moment an account is downgraded or cancelled.
  • An API key. Create one as described in API keys. It is shown once and never again.
  • Credits in the monthly allowance. Most tools cost 1 to 4 credits and twelve of them are free.
  • Any agent or script that can make an HTTP request. Nothing to install.

Permissions#

A key belongs to one account and is never shared with a teammate.

A key can only run tools. It reaches the /api/v1/ routes and nothing else: presenting it anywhere else in the product authenticates nothing. It cannot read your Library, change settings, manage your team or touch billing. Giving an agent a key is therefore a much smaller grant than giving it your password, and the worst a mistake can do is spend credits.

Admin console at metricvaultai.com/admin, then API Access in the left navigation. That screen creates and revokes keys, lists every callable tool with its cost, and shows when each key was last used.

Step-by-Step Guide#

1. Store the key so every folder can see it#

Put the key in your shell environment rather than in one project's files, so it is available wherever you open the agent.

On macOS or Linux:

bash
echo 'export MV_API_KEY=mv_live_your_key_here' >> ~/.zshrc
source ~/.zshrc

On Windows, in PowerShell:

powershell
[Environment]::SetEnvironmentVariable('MV_API_KEY', 'mv_live_your_key_here', 'User')

Close and reopen the terminal, then confirm it is set. This should print the key:

bash
echo $MV_API_KEY

On Windows the same check is echo $env:MV_API_KEY.

Never paste the key into a chat message, a ticket or a commit, and never type it directly on a command line, because that saves it into your shell history. If it is ever exposed, revoke it and create another. Revoking takes effect immediately and affects nothing else.

2. Tell the agent the key exists#

Paste this once at the start of a session:

text
I have a Metric Vault API key in the MV_API_KEY environment variable.
Use it to run SEO tools for me. Two endpoints, both authenticated with
Authorization: Bearer $MV_API_KEY

  GET  https://metricvaultai.com/api/v1/tools
       Lists every tool you can run. Each entry gives:
       tool (the id to send), label, description,
       input (the kind of value it takes), credits (what it costs).

  POST https://metricvaultai.com/api/v1/run
       Body: {"tool": "<id>", "input": "<the one value>"}
       Optional: country, device, range, intent.

Fetch the catalog first so you know what exists, then pick the tool
yourself. Every tool takes exactly one input value. If a request is
refused, read the code field and tell me what it says rather than
retrying.

To avoid pasting it each time, save that text as CLAUDE.md in the folder you work in and Claude Code reads it automatically at the start of every session.

3. Prove it works, for free#

Ask for something that costs nothing, such as "run a page speed check on example.com". That exercises the key, the network and the plan check without spending a credit. If it returns a result, everything is configured.

4. Ask for the work#

Use your own words. The agent maps them to a tool:

AskIt runs
What is the volume and difficulty for "seo software"?Keyword Overview
Give me 50 keyword variations around "local seo"Keyword Explorer
How much organic traffic does competitor.com get?Domain Overview
Who links to competitor.com, and is any of it toxic?Backlink Profile
What keywords does competitor.com already rank for?Organic Research
Do AI assistants mention us in our category?AI Visibility
Check the speed of our pricing pagePage Speed, free
Does our pricing page work on a phone?Responsiveness Check, free

The larger gain is work that chains, where you ask for an outcome instead of a step:

  • "Find the ten best keywords for project management software, then write a brief for the strongest one." Keyword Explorer, then Keyword Overview on the candidates, then SEO Brief.
  • "Compare us with these three competitors on traffic, keywords and backlinks, and put it in a table." Three tools across four domains, then assembled.
  • "Audit the technical health of our top five pages." The free URL tools in a loop, at no cost.

A chained request can be ten or more calls, so one sentence from you is sometimes thirty credits. That is usually the right trade, but it is worth knowing before you ask for something broad.

5. Watch the spend#

Every call is recorded against the account exactly as a dashboard run is. Usage on the admin console shows credits consumed, and DataForSEO Ops shows what the underlying data provider charged. API Access shows when each key was last used, which is the quickest way to tell whether a key is still in service. See Credit cost table for per-tool prices.

Examples#

The same two calls by hand, if you want to see the shape underneath:

bash
# what can this key run?
curl -s https://metricvaultai.com/api/v1/tools \
  -H "Authorization: Bearer $MV_API_KEY"

# run one
curl -s https://metricvaultai.com/api/v1/run \
  -H "Authorization: Bearer $MV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"keyword_overview","input":"seo software"}'

A delivered run returns the tool that ran, the input, what it cost, and the tool's own payload under result.

Troubleshooting#

Every refusal carries a short code. Ask the agent to report it rather than retry, because the code names the cause. The full list is in Error codes.

CodeCauseWhat to do
no_keyNo key reached the serverThe variable is not set in that terminal. Reopen it and check echo $MV_API_KEY
bad_keyUnknown or revoked keyCreate a new one. The two cases answer identically on purpose, so a stranger guessing learns nothing
upgrade_requiredThe account is not on EnterpriseCheck the plan on the account
unknown_toolNo such toolThe agent guessed a name instead of reading the catalog. Tell it to fetch the tool list first
no_inputNo value was givenThe reply names which kind of input that tool wants
account_suspendedThe account is suspendedContact support

A 503 means the tool is briefly switched off or the data provider is unreachable, so wait and retry. An empty result is a real answer rather than a failure: some domains and keywords genuinely have no data.

FAQs#

Does a refused call cost anything? No. A refusal costs nothing, and a run that fails partway returns its credits, so a run of errors cannot quietly drain the allowance.

Can the agent change anything in my account? No. A key runs tools and nothing else. It cannot reach settings, billing, your team or your saved work.

Which tools are not available this way? The ones that take more than one input, among them Gap Finder, Competitor Battle, Backlink Gap, Content Optimizer and SEO Compare. An agent would have to guess the second value, so they stay in the dashboard.

Do API runs appear in my Library? Yes. A run through the API is saved and metered exactly as the same run started in the dashboard, so the two sit together rather than in separate pots.

Do I have to update anything when a tool is added? No. The agent reads the catalog at the time it asks, so a new tool is callable straight away and a changed price is reported before you are charged it.

Can I use something other than Claude Code? Yes. Nothing here is specific to one agent. Any tool that can make an HTTP request with a bearer token works, including a plain shell script.

See also

Was this article helpful?