Companies

Search never returns company records. It returns encrypted string company IDs, and you pass up to 100 of them to the detail route to read the records. There is no one-shot endpoint, so plan for two calls.

# 1. Search. Returns encrypted IDs, never records.
curl -X POST "https://mira-api.metix.ai/v1/companies/query" \
  -H "Authorization: Bearer $METIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {"all": [
      {"field": "categories_and_keywords", "match": "artificial intelligence"},
      {"field": "hq_country", "match": "United States"},
      {"field": "employees_count", "gte": 50},
      {"field": "employees_count", "lte": 500},
      {"not": {"field": "type", "eq": "Public Company"}}
    ]},
    "size": 25
  }'

# 2. Read the records, up to 100 IDs per call.
curl -X POST "https://mira-api.metix.ai/entity/v1/companies/detail-by-id" \
  -H "Authorization: Bearer $METIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_ids": ["Cm4vTnR2sD", "CmZp8Lk1uH"],
    "_source": ["id", "name", "industry", "size_range", "hq_full_address"]
  }'

• Build an account list by industry, size, headquarters, or funding.
• Attach organization context to a job or profile result set.
• Separate B2B from B2C, or public from private, before a market count.

• One operator per leaf. A headcount band is an all of two leaves, not gte and lte in one node.
• A field name that is not in this dataset's list is refused, so a typo is visible rather than returning a record without it. The three datasets do not share one vocabulary.
• Search returns at most 10,000 IDs per page and 100 when size is omitted; detail accepts at most 100 IDs per request.
• Companies declare no scope nodes. One document is one company, so there is nothing to group.
• The response carries IDs and a cursor, not a match count. Page until next is absent if you need the size of a set.
• Company data is a periodically refreshed snapshot and can lag real-world changes.

These are the only names a leaf may put in field. The grammar around them, including composition, one operator per leaf, and relative dates, is on the Query Spec page. What a response may contain is a separate, wider list: a field can be returnable without being queryable.

{
  "where": {
    "all": [
      {
        "field": "industry",
        "match": "software"
      }
    ]
  }
}

{
  "where": {
    "all": [
      {
        "field": "hq_country",
        "match": "United States"
      },
      {
        "field": "hq_city",
        "match": "Austin"
      }
    ]
  }
}

{
  "where": {
    "all": [
      {
        "field": "stock_exchange",
        "exists": true
      }
    ]
  }
}

{
  "where": {
    "all": [
      {
        "field": "size_range",
        "eq": "51-200 employees"
      },
      {
        "field": "is_b2b",
        "eq": true
      }
    ]
  }
}

{
  "where": {
    "all": [
      {
        "field": "employees_count",
        "gte": 500
      },
      {
        "field": "employees_count",
        "lte": 5000
      }
    ]
  }
}

{
  "where": {
    "all": [
      {
        "field": "last_funding_round_amount_raised",
        "gte": 1000000
      }
    ]
  }
}

{
  "where": {
    "all": [
      {
        "field": "last_funding_round_date",
        "gte": "now-3y"
      }
    ]
  }
}

These are matched against the whole stored value, so the spelling and the capitalisation both have to match. Getting either wrong is the one mistake in the grammar that raises no error: the query is valid, it costs nothing, and it returns zero, which reads as an answer about the data rather than about the query.

Successful responses use the public envelope with code, msg, and data.

Search returns IDs, and a next cursor while more pages remain:

{
  "code": 200,
  "msg": "ok",
  "data": {
    "company_ids": ["Cm4vTnR2sD", "CmZp8Lk1uH"],
    "next": "WzE3MjQwMDAwMDAsIkNtNHZUblIyc0QiXQ"
  }
}

Detail returns the records, and names the IDs it could not resolve:

{
  "code": 200,
  "msg": "ok",
  "data": {
    "total": 2,
    "found": 2,
    "not_found": [],
    "results": [{
      "id": "Cm4vTnR2sD",
      "name": "Example Corp",
      "industry": "Software Development",
      "size_range": "201-500 employees",
      "hq_full_address": "San Francisco, CA, United States"
    }]
  }
}

The record itself is a page of its own: every field it can carry, what each one holds, and a whole one to read.

Common next step: find the people inside those companies.