How the API works
Search wide, read narrow, pay for what you read.
Metix AI Platform splits every lookup into two steps. A search finds matches and hands back IDs. A second call turns the IDs you keep into records. Searching costs about a fifth of what reading does, so you can sweep a whole market cheaply and spend only on the rows you actually want.
The flow
The whole flow, in four steps.
01
Connect
Create a key on the API keys page. Keys start with
metix_. Use the key over REST, or register the MCP server in your agent with that key. Checking a key's status, scopes and remaining API Credits costs nothing.export METIX_KEY="metix_xxxxxxxxxxxx" # Free: scopes, rate limit, API Credits left GET /auth/key/status02
Search
Describe what you want as a Query Spec tree: fields, operators, and
all,anyornotaround them. A Query Spec search returns encrypted IDs, a total and a cursor for the next page. For people, you can also describe them in a sentence; that search returns encrypted IDs only, with no total and no cursor, so it cannot be paged. No search returns names, employers or posting text.POST /v1/people/query {"where": {"all": [ {"field": "current_title", "match": "machine learning engineer"}, {"field": "location.city", "eq": "San Francisco"} ]}, "size": 25} # → profile_ids, total, next03
Read
Send up to 100 IDs to the detail route for that dataset, and name the fields you want or take the default set. You get exactly the records you asked for, and those are the records you pay for.
POST /entity/v1/profiles/detail-by-id {"profile_ids": [ ...up to 100 ids from step 02 ]}04
Unlock contact
Optional, paid accounts
For people you have already found, ask for a work email, a personal email or a phone number. You pay only for values found. Asking again for the same person and the same kind within 30 days is free.
POST /v1/contact/unlock {"people": [{"profile_id": "kR3nQv8xTm"}], "fields": ["work_email"]}
Two ways in
Ask in plain words, or call it from code.
With your agent
Register the MCP server once, then ask in plain words: "Which companies are hiring machine learning engineers in New York this week?" The agent reads the live contract first (that call is free), writes the query, runs the search and fetches the records it needs. It works today in Claude Code, Codex, Grok Build and Muse, and the skills package teaches any agent the same steps.
claude mcp add --transport http metix-ai-platform \
https://mira-api.metix.ai/mcp \
--header "Authorization: Bearer $METIX_KEY"With your code
The same calls over REST, at https://mira-api.metix.ai, with the key in a Bearer header. Every MCP tool has a REST route behind it. A few routes carry no tool, because an agent has no use for a health check or for the teaching pages. Contact unlock works over both, but over MCP it needs a connection you granted the contact:unlock scope, because it is the one tool that spends API Credits.
POST /v1/jobs/query
# → job_ids
POST /entity/v1/jobs/detail-by-id
# → job recordsOne grammar
Three datasets, one way to ask.
People, job postings and companies all take the same where tree. Only the field list changes between them, so a query you learn on people works on jobs and companies too.
Each field takes particular operators. Free text takes match, categories and names take eq or in, and numbers and dates take the range operators. The live contract lists every field and its operators. An unknown field or a malformed tree is refused before anything runs, and you are not charged for it.
POST /v1/jobs/query
{"where": {"all": [
{"field": "title", "match": "data engineer"},
{"field": "location.country", "match": "United States"},
{"field": "posted_date", "gte": "now-30d"}
]}, "size": 25}What it costs
Each step has its own price.
Per step
- Search
- 1 API Credit per 25 IDs returned
- Search described in a sentence (people)
- The same, plus a 5 API Credit base
- Read
- 1 API Credit per 5 records
- Work email, personal email, phone
- 3, 8 or 15 API Credits per value found
- Contract, key status, refused requests, empty searches, values not found
- Free
Example
Find 1,000 engineers and read 200 of them. That is 40 API Credits for the search plus 40 for the records, 80 in total, or $2.40 on the Go plan.
Plans
Free
$0
100 API Credits, one time, valid 30 days
Go
$9
300 API Credits per month
Plus
$19
1,000 API Credits per month
Pro
$59
5,000 API Credits per month
Plans change how many API Credits you get each month, not the rate. Pay as you go is $1 for 30 API Credits, from $10, and purchased API Credits never expire.
Limits
Limits you can plan around.
- Requests per minute, per key
- 60
- Requests per minute, per client address
- 120
- IDs per search page
- 100 by default, up to 10,000
- IDs per detail call
- Up to 100
- Search total
- Exact below 100,000, reported as
100000+above
Paging
Pages are not a snapshot. The cursor stores no state and never expires, but a record indexed while you are paging can appear on a later page, move, or be missed. If you need an exact set, narrow the query until it fits in one page.
When something goes wrong
One envelope for every answer.
Every response comes in the same envelope, so your error path is the same code as your success path. A refused request carries an error_code to switch on and a docs_url that explains the failure and how to fix it. A request refused for being wrong costs nothing. When you hit the rate limit, you get a 429 with a Retry-After header.
See it on a real question
The bill is on the page.
Every Casebook entry shows the prompt, the calls, the data and the bill. For example, find which of your accounts are hiring for a role costs 18 API Credits to reproduce.
Questions
Questions
- Why does a search return IDs instead of records?
- Because finding and reading are priced differently. IDs let you sweep wide for little and pay for full records only where you want them.
- Do I need to write code?
- No. Connect the MCP server or the skills package to your agent and ask in plain words. The REST API is there when you want to build it into your own product.
- What happens when my agent writes a bad query?
- The API refuses it before running it, charges nothing, and returns an
error_codewith a link that explains the fix. An agent can read that link and correct the query.
Who builds the Platform, and how it differs from Metix AI: About.
Start with 100 API Credits.
Which is 2,500 search results or 500 records, free, on a key you create yourself in about a minute. No card, and no sales call.