Get started
Search wide, then read narrow.
Every search answers with encrypted ids, and a second call turns the ids you keep into records. Searching is the cheap half, so filter as hard as you like before you read. All three datasets work exactly this way.
Four ways to ask
Same request, four interfaces. The top two are sentences you type at an agent; the bottom two are calls you build. Switch between them and the bottom half stays the same, because it is the same two endpoints underneath.
Nothing to look up. The skill knows the two-step shape and reads field names and operators from GET /contract when it runs, so plain English is the whole interface.
Find machine learning engineers in San Francisco,
then show me their current titles and employers.# The skill knows both calls. It reads the field names
# and operators from the live contract first.
GET /contract
POST /v1/people/query
{"where": {"all": [
{"field": "current_title", "match": "machine learning engineer"},
{"field": "location.city", "eq": "San Francisco"}]}, "size": 25}
POST /entity/v1/profiles/detail-by-id
{"profile_ids": [ ...the 25 ids from above ]}No key yet? Create one in the dashboard. The free plan starts with 100 API Credits and needs no card.
The shape of every request
Every search route answers with encrypted string ids and no record data at all. To read the records you send up to 100 of those ids to the detail route for the same dataset. There is no single call that does both, and no phrasing of a search that makes records come back early.
The practical consequence is worth stating on its own: a response full of ids means the search worked. Code that reads a search response looking for names finds nothing and concludes the dataset is empty. It is not. The names are one call away.
- Dataset
- People
- Search with
- POST /v1/people/query or /v1/people-search
- Then read with
- POST /entity/v1/profiles/detail-by-id
- Ids are called
- profile_ids
- Dataset
- Jobs
- Search with
- POST /v1/jobs/query
- Then read with
- POST /entity/v1/jobs/detail-by-id
- Ids are called
- job_ids
- Dataset
- Companies
- Search with
- POST /v1/companies/query
- Then read with
- POST /entity/v1/companies/detail-by-id
- Ids are called
- company_ids
An id never changes, so you can store one and read the record later with the same detail call, and a pipeline can re-read records on its own schedule rather than re-running the search. A record can leave the index (a job posting closes, for example), and its id then comes back in not_found.
Wire it into an agent
We run an MCP server at https://mira-api.metix.ai/mcp over streamable HTTP, with legacy SSE on /sse for older clients. Both authenticate with the same Bearer key as the REST API and settle against the same API Credit balance. One line registers it. Keep --scope user: without it the server is registered against the directory you happened to run the command in, and it will be missing from the next project you open.
claude mcp add --scope user --transport http metix-ai-platform \
https://mira-api.metix.ai/mcp \
--header "Authorization: Bearer $METIX_KEY"Codex takes the key from your environment instead of writing it into the config file:
codex mcp add metix-ai-platform \
--url https://mira-api.metix.ai/mcp \
--bearer-token-env-var METIX_KEYAny other MCP client needs four facts: the URL above, the streamable HTTP transport, an Authorization: Bearer header carrying your key, and an Accept: application/json, text/event-stream header, without which the server answers 406. The handshake on the MCP page sends all four.
An app with a connector form rather than a terminal does not need the key at all. Claude.ai, ChatGPT and Grok on the web take the URL and then send you here to sign in, so nothing is pasted and no key is created. What that grants, and the one thing it holds back, is on the MCP page; the steps per app are on integrations.
Agents that do not speak MCP can install the skills instead. They are plain instructions that know these endpoints and the two-step shape, and they read field names and operators from GET /contract when they run. They read the same METIX_KEY as everything else on this page, and they install for Codex as well as for Claude Code:
npx skills add MetixAI-Official/metix-skills
export METIX_KEY="metix_xxxxxxxxxxxx"If the agent still has the retired OpenJobs skills installed, remove them first, or it will sometimes follow those instead. The skills page has the commands and a prompt you can hand the agent.
Reading this page as an agent
Run it yourself
Create a key under API Keys and export it once. Keys begin with metix_; one issued before that rename begins with mira_ and keeps working, so there is nothing to rotate. Keep the value out of source control and out of anything the browser can read.
export METIX_KEY="metix_xxxxxxxxxxxx"
# Free, and worth doing first: scopes, rate limit, remaining quota.
curl -s "https://mira-api.metix.ai/auth/key/status" \
-H "Authorization: Bearer $METIX_KEY"A 401 with missing_api_key or invalid_api_key means the header is wrong or empty: send Authorization: Bearer $METIX_KEY, and check the shell expanded the variable. A 403 means the key is disabled or out of scope. A 402 with insufficient_quota on a later call means the balance is exhausted. The error catalog lists each code.
Every refusal also carries error_code and docs_url, the documentation page for that error. An agent should fetch docs_url with .md added to the path, ahead of any fragment: /docs/reference/errors#query-refusals becomes /docs/reference/errors.md. The fragment names the section, and the Markdown marks each section with an anchor of the same id.
Now the first call. Machine learning engineers in San Francisco is two fields, so it goes to the Query Spec route: current_title is free text and takes match, and location.city is an exact value and takes eq. The sample keeps the response in $search so the next step can read the ids from it.
/v1/people/querysearch=$(curl -s -X POST "https://mira-api.metix.ai/v1/people/query" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d '{
"where": {"all": [
{"field": "current_title", "match": "machine learning engineer"},
{"field": "location.city", "eq": "San Francisco"}
]},
"size": 25
}')
printf '%s\n' "$search"{
"code": 200,
"msg": "ok",
"data": {
"profile_ids": [
"UHyKQXeFCLaGeBwgjwisBg",
"YhlkBSsJWv7zeGUJMaymMw",
"E-i6XGwZbYe-8QkHWd5Tbw",
...
],
"total": 1843,
"next": "WzUuMDM1MTYwNSw1OTcyMTgzNjBd"
}
}Ids, exactly as promised, with a total and a next cursor and no record data. The call costs one API Credit per 25 ids returned, and nothing when it finds nobody. Hand the ids to the profile detail route, up to 100 per request, and choose the fields you want back with _source. Omit _source and you get the default set. The block below takes the first five ids out of $search with jq, so run it in the same shell.
/entity/v1/profiles/detail-by-id# The first five ids from the search above. Five records cost 1 API Credit.
ids=$(printf '%s\n' "$search" | jq '.data.profile_ids[:5]')
jq -n --argjson ids "$ids" '{
profile_ids: $ids,
_source: ["profile_id", "full_name", "current_title", "skills"]
}' | curl -s -X POST "https://mira-api.metix.ai/entity/v1/profiles/detail-by-id" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d @-{
"code": 200,
"msg": "ok",
"data": {
"total": 5,
"found": 5,
"not_found": [],
"results": [
{
"profile_id": "UHyKQXeFCLaGeBwgjwisBg",
"full_name": "Jordan Reyes",
"current_title": "Machine Learning Engineer",
"skills": ["machine learning", "model deployment", "pytorch"]
},
...
]
}
}Detail answers with found and not_found alongside the records, so a partial resolve is visible rather than silent. Ids that resolve to nothing are not charged.
Some briefs will not sit on fields. Natural-language people search takes one as a sentence in text and returns profile ids. Each successful call carries a 5 API Credit base on top of the per-result rate, even one that finds nothing, and the response holds profile_ids only, with no total and no next. Use it when you cannot name the constraints as fields. It fills $search the same way, so the detail block above reads its ids unchanged.
/v1/people-search# A 5 API Credit base on every successful call, even an empty one,
# plus 1 API Credit per 25 ids returned.
search=$(curl -s -X POST "https://mira-api.metix.ai/v1/people-search" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "engineers who moved from academic research into applied machine learning at early-stage startups", "size": 25}')
printf '%s\n' "$search"{
"code": 200,
"msg": "ok",
"data": {
"profile_ids": [
"YhlkBSsJWv7zeGUJMaymMw",
...
]
}
}Exact conditions, and the other two datasets
Query Spec is the route for any brief you can name as fields: a named employer, a country, a numeric range. It is exact and repeatable, with no base charge, and all three datasets take the same tree, so the jobs and companies examples below are the people example with different field names.
A tree is composed with all, any and not, and each leaf carries exactly one of eq, in, match, gte, gt, lte, lt or exists.
Which of those a field accepts depends on its kind, and each dataset page lists them field by field: people, jobs and companies. A field name is the path the record returns the value under, so experience.company.name is both the filter and where you read the employer. Exact-value fields, such as a person's location.country or experience.function, a company's type and every yes/no field, take eq, in and exists, and refuse match. Free-text fields, such as a title, take match, eq, in and exists. Numbers and dates take eq, in, gte, gt, lte, lt and exists, and so do fields with an ordered list of values, such as education.degree, which compare by position in that list.
# People: currently working machine learning engineers in San Francisco
curl -s -X POST "https://mira-api.metix.ai/v1/people/query" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d '{
"where": {"all": [
{"field": "current_title", "match": "machine learning engineer"},
{"field": "location.city", "eq": "San Francisco"},
{"field": "is_employed", "eq": true}
]},
"size": 25
}'
# Jobs: US data engineering roles posted in the last 30 days
curl -s -X POST "https://mira-api.metix.ai/v1/jobs/query" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d '{
"where": {"all": [
{"field": "title", "match": "data engineer"},
{"field": "location.country", "match": "United States"},
{"field": "posted_date", "gte": "now-30d"}
]},
"size": 25
}'
# Companies: US biotechnology companies with 50 to 500 employees
curl -s -X POST "https://mira-api.metix.ai/v1/companies/query" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d '{
"where": {"all": [
{"field": "industry", "match": "biotechnology"},
{"field": "headquarters.country", "match": "United States"},
{"field": "headcount", "gte": 50},
{"field": "headcount", "lte": 500}
]},
"size": 25
}'Each of those answers with the id list for its dataset, a total (an exact count below 100,000, or the string "100000+"), and a next cursor while pages remain. Feed the ids to that dataset's detail route exactly as the people example does.
Two leaves, not two operators
{"field": "headcount", "gte": 50, "lte": 500} is refused rather than half-applied.People carry same-record scopes
has_experience, has_education and has_language exist to say "one job that is both at Google and at director level" rather than "some job at Google, and separately some job at director level". Everything inside one scope must match the same record. See the Query Spec grammar.More than one page
A Query Spec response carries a next value while more results remain. Send it back unchanged as after to get the following page, and keep the rest of the request identical. When next is absent you have reached the last page. The block below keeps the tree in one variable, so both pages send the same request, and asks for page two only when page one sent a cursor.
query='{
"where": {"all": [
{"field": "title", "match": "data engineer"},
{"field": "location.country", "match": "United States"},
{"field": "posted_date", "gte": "now-30d"}
]},
"size": 25
}'
# Page one. Keep its next value; it is null on the last page.
next=$(curl -s -X POST "https://mira-api.metix.ai/v1/jobs/query" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d "$query" | jq -r '.data.next // empty')
# Page two, only when page one sent next. No next means page one was
# the last page, and an empty after is not a cursor to resume from.
if [ -n "$next" ]; then
jq -n --argjson q "$query" --arg after "$next" '$q + {after: $after}' \
| curl -s -X POST "https://mira-api.metix.ai/v1/jobs/query" \
-H "Authorization: Bearer $METIX_KEY" \
-H "Content-Type: application/json" \
-d @-
fiPages are not a snapshot
Where to go next
API Credit settlement