Skip to main content
Search returns a JSON object with a data array of organisation rows and a metadata object (total hits, mode, timing, pagination cursor, filters applied).

​
Requirements

You must supply at least one of:
  • filters: column filters only (browse / filter mode)
  • keywords: BM25 text search
  • describe: natural-language description → embedding search (cannot be combined with similar_to)
  • similar_to: similarity to one or more reference domains (cannot be combined with describe)
similar_to and describe are mutually exclusive.

​
Search mode (automatic)

You do not send a mode name. The API infers it from your inputs:
metadata.mode valueWhen it runs
filterOnly filters (no keywords, describe, or similar_to)
fulltextkeywords only (no describe, no similar_to)
semanticdescribe only
vector_similaritysimilar_to only
hybridkeywords together with similar_to or with describe
Hybrid queries blend BM25 and vector ranking (reciprocal rank fusion). Use search_balance from 0.0 (BM25-heavy) to 1.0 (vector-heavy); default 0.5.

​
Request body (overview)

{
  "similar_to": ["stripe.com"],
  "describe": null,
  "keywords": { "must_all": [], "must_any": [], "must_not": [] },
  "filters": { },
  "excludes": [],
  "columns": ["domain", "name", "country"],
  "size": 100,
  "min_score": null,
  "search_balance": 0.5,
  "search_after": null,
  "dedup": false
}
FieldNotes
columnsSubset of allowed columns; domain is always returned. Default ["domain", "name", "country"]. See Reference.
sizePage size, default 100, maximum 500.
min_scoreOptional 0.0–1.0 cosine similarity floor for vector / semantic / hybrid modes.
search_afterOpaque cursor from the previous response’s metadata.search_after for pagination.
dedupIf true, collapse rows that share the same organization name, keeping the best match until size rows.

​
Keywords (keywords)

Drives BM25 search on name and description (and participates in hybrid): 
{
  "must_all": ["payments", "B2B"],
  "must_any": ["SaaS", "cloud"],
  "must_not": ["crypto"]
}
All parts are optional, but must_not alone is invalid: you need at least one of must_all or must_any whenever must_not is present.

​
Similar organizations (similar_to)

Pass up to three domains as strings, or as objects for steering (boost / penalize terms, repel domains, weight): 
{
  "similar_to": [
    {
      "domain": "stripe.com",
      "boost": ["enterprise", "B2B"],
      "penalize": ["consumer"],
      "repel_domains": ["paypal.com"],
      "weight": 1.0
    }
  ]
}
  • boost, penalize, repel_domains: up to 5 entries each.
  • weight: number from 0.0 to 2.0, or the strings weak, normal, strong (mapped to internal numeric weights). Default 1.0.

​
Semantic description (describe)

Free-text description of the kind of organizations you want; embedded and searched like a vector query. Cannot be used together with similar_to.

​
Filters (filters)

Optional on any mode. Multiple values in a list are OR-combined for that field. Full field list and semantics: Reference, filters. Inside filters, text_keywords uses the same shape as top-level keywords but acts as a strict BM25 filter on text (slower than summary_keywords for exact keyword-array matches).

​
Excludes

excludes is a list of domains that must not appear in results, regardless of score.

​
Pagination

  • First page: omit search_after or send null.
  • Next page: copy metadata.search_after from the previous response into the next request.
Scored modes use an offset-style cursor with a maximum depth of 10,000 rows. Filter-only mode uses keyset pagination by domain and has no depth cap. When metadata.search_after is null, there is no further page.

​
Example requests

Filter-only browse (Germany): 
{
  "filters": { "country": ["Germany"] },
  "size": 50
}
Keyword search with geography: 
{
  "keywords": { "must_any": ["renewable energy", "solar"] },
  "filters": { "country": ["Germany", "Austria"] }
}
Similar to a reference organization: 
{
  "similar_to": ["stripe.com"],
  "filters": { "country": ["Ireland", "Germany"] },
  "columns": ["domain", "name", "country", "nace_code"]
}
Hybrid (keywords + description): 
{
  "keywords": { "must_all": ["HR", "software"] },
  "describe": "payroll automation for SMEs",
  "search_balance": 0.6,
  "size": 20
}

​
Response shape

{
  "data": [
    { "domain": "example.com", "name": "Example GmbH", "country": "Germany" }
  ],
  "metadata": {
    "total_hits": 142,
    "returned": 25,
    "mode": "hybrid",
    "elapsed_ms": 312,
    "search_after": [25],
    "filters_applied": { "country": ["Germany"] }
  }
}
total_hits may be null in some filter paths. See Errors for failure responses.