Skip to main content
Search returns the most relevant records for a query, ranked by relevance rather than recency. Use it when you want to find things by meaning or keyword, instead of paging through an entire collection. Each core resource exposes a search endpoint that accepts a POST body:
ResourceEndpoint
CompaniesPOST /v1/companies/search
DealsPOST /v1/deals/search
PeoplePOST /v1/people/search
DocumentsPOST /v1/documents/search

​
Making a search request

Send a JSON body with your query and optional pagination. Results come back under data, with pagination details in metadata. 
curl -X POST https://api.metal.ai/v1/companies/search \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "industrial automation suppliers", "limit": 20 }'

{
  "data": [
    {
      "id": "665f1c2a9b1e4a0012a3b4c5",
      "canonicalName": "Acme Industrials",
      "sector": "Industrials"
    }
  ],
  "metadata": {
    "page": 1,
    "limit": 20,
    "totalCount": 134,
    "totalPages": 7
  }
}

​
Searching documents

Document search is the way to query the content your firm has ingested into Metal. It matches across parsed document text, so you can find passages and files by meaning. 
curl -X POST https://api.metal.ai/v1/documents/search \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "customer concentration risk", "limit": 10 }'

​
Search vs. list

Use search

When you want relevance — finding records that match a concept, phrase, or keyword.

Use list

When you want completeness — iterating over every record in order. See Pagination.
Search responses include a metadata object with page, limit, totalCount, and totalPages. Request additional pages by passing page and limit in the body. Deep pagination is bounded: very large page × limit offsets are rejected, so narrow your query rather than paging endlessly.