Fetch & statistics

Base URL prefix: https://api.istari.ai/v2.

`POST /fetch` : bulk domain lookup

Returns current GOI rows for domains you already know. There is no relevance ranking.

Request

{
  "domains": ["stripe.com", "adyen.com", "unknown.example"],
  "columns": ["domain", "name", "country", "nace_code"]
}

domains: required, non-empty list, maximum 5,000 domains per request.
columns: same rules as search; default ["domain", "name", "country"]. See Reference: columns.

Domains your key is not allowed to see are treated like missing and appear in metadata.missing.

Response

{
  "data": [ … ],
  "metadata": {
    "requested": 3,
    "found": 2,
    "missing": ["unknown.example"]
  }
}

`POST /stats` : aggregations

Returns COUNT(*) buckets over the filtered population. No text or vector scoring, plain SQL grouping. Available on all customer API tiers. Monthly request quotas apply by tier (see Reference: rate limits).

Request (shape)

{
  "group_by": "nace_code",
  "group_by_secondary": "organization_size",
  "date_trunc": "month",
  "filters": { "country": ["Germany"] },
  "date_range": {
    "field": "company_register_date",
    "from_date": "2020-01-01",
    "to_date": "2024-12-31"
  },
  "limit": 100
}

Field	Description
`group_by`	Optional. Primary dimension to bucket by. Omit for a single total count.
`group_by_secondary`	Optional second dimension (2D breakdown). Requires `group_by`. Must differ from `group_by`.
`date_trunc`	`year`, `month`, or `week`: used when a grouping column is a date (`company_register_date`, `created_at`).
`filters`	Same column filters as `/search`. `text_keywords` is not supported in stats.
`date_range`	Optional bounds on `company_register_date`, `created_at`, or `updated_at`.
`limit`	Max buckets returned (default `100`, max `500`). Ordered by count descending, except date dimensions (chronological ascending).

Allowed `group_by` / `group_by_secondary` columns

Geographic: continent, country, country_code, state, state_code, region, region_code, district, district_code, municipality, municipality_code. Classification: nace_code, organization_type, organization_size, employee_class, revenue_class. Source / registry: source, company_register_court. Array (exploded per value): summary_keywords. Date (use with date_trunc): company_register_date, created_at.

Response

Each bucket in data includes the grouping column value(s) and a count. Top-level elapsed_ms and metadata echo timings, filters, and bucket counts.

`GET /filters/options`

Returns JSON suitable for building filter UIs: allowed categorical values, scoped to your API key’s data access. No request body.

`GET /health`

Lightweight check that the service can reach the database. Response shape:

{ "healthy": true }

or, on failure, healthy: false with an error message.

Minimal `curl` : fetch

curl -sS 'https://api.istari.ai/v2/fetch' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_KEY' \
  -d '{"domains":["istari.ai"],"columns":["domain","name","country"]}'

Getting Started

Global Organization Index

GOI API

GOI MCP

Research Data

`POST /fetch` : bulk domain lookup

Request

Response

`POST /stats` : aggregations

Request (shape)

Allowed `group_by` / `group_by_secondary` columns

Response

`GET /filters/options`

`GET /health`

Minimal `curl` : fetch

​POST /fetch : bulk domain lookup

​Request

​Response

​POST /stats : aggregations

​Request (shape)

​Allowed group_by / group_by_secondary columns

​Response

​GET /filters/options

​GET /health

​Minimal curl : fetch

`POST /fetch` : bulk domain lookup

Request

Response

`POST /stats` : aggregations

Request (shape)

Allowed `group_by` / `group_by_secondary` columns

Response

`GET /filters/options`

`GET /health`

Minimal `curl` : fetch