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.

  1. 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/status
  2. 03

    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 ]}
  3. 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 records

One 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_code with 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.