Skip to main content
POST
/
stats
Aggregate counts — group by dimension(s) with filters
curl --request POST \
  --url https://api.istari.ai/v2/stats \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "group_by": "<string>",
  "group_by_secondary": "<string>",
  "date_trunc": "month",
  "filters": {
    "country": [
      "<string>"
    ],
    "state": [
      "<string>"
    ],
    "region": [
      "<string>"
    ],
    "district": [
      "<string>"
    ],
    "municipality": [
      "<string>"
    ],
    "organization_type": [
      "<string>"
    ],
    "organization_size": [
      "<string>"
    ],
    "nace_code": [
      "<string>"
    ],
    "source": [
      "<string>"
    ],
    "company_register_court": [
      "<string>"
    ],
    "register_date_from": "2023-12-25",
    "register_date_to": "2023-12-25",
    "summary_keywords": [
      "<string>"
    ],
    "text_keywords": {
      "must_all": [
        "<string>"
      ],
      "must_any": [
        "<string>"
      ],
      "must_not": [
        "<string>"
      ]
    }
  },
  "date_range": {
    "from_date": "2023-12-25",
    "to_date": "2023-12-25"
  },
  "limit": 100,
  "explain": false
}
'
{
  "data": [
    {}
  ],
  "elapsed_ms": 123,
  "metadata": {
    "group_by": "<string>",
    "group_by_secondary": "<string>",
    "date_trunc": "<string>",
    "filters_applied": {},
    "date_range_applied": {},
    "total_buckets": 123,
    "elapsed_ms": 123,
    "explain_plan": [
      "<string>"
    ]
  }
}

Authorizations

​
x-api-key
string
header
required

Your GOI API key. Create one on the GOI dashboard under API keys.

Body

application/json
​
group_by
string | null

Primary dimension to group by. Omit for a single total COUNT(*). Allowed values — 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: source. Array (unnested per keyword): summary_keywords. Registrations (unnested per registration via the registries jsonb): company_register_court, company_register_date. A company with multiple registrations contributes one row per registration. Date (requires date_trunc): company_register_date, created_at.

​
group_by_secondary
string | null

Optional second dimension — produces a 2D breakdown. Requires group_by to be set. Allowed values — 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: source. Array (unnested per keyword): summary_keywords. Registrations (unnested per registration via the registries jsonb): company_register_court, company_register_date. A company with multiple registrations contributes one row per registration. Date (requires date_trunc): company_register_date, created_at.

​
date_trunc
enum<string>
default:month

Truncation unit applied when group_by or group_by_secondary is a date column (company_register_date or created_at). Ignored for non-date columns. Results are ordered chronologically (ASC) when a date dimension is active.

Available options:
year,
month,
week
​
filters
FiltersInput · object

Column filters to narrow the counted population — same fields as /v1/search filters. text_keywords is not supported here (no BM25 in aggregation queries).

​
date_range
DateRangeFilter · object

Optional date range filter on company_register_date or created_at. Can be combined with filters and with a date group_by dimension simultaneously.

​
limit
integer
default:100

Maximum number of buckets to return, ordered by count DESC (or ASC for date dimensions). Default 100, max 500.

Required range: 1 <= x <= 500
​
explain
boolean
default:false

Return EXPLAIN ANALYZE plan in metadata. Sets a 120s statement timeout. Not available for customer API keys.

Response

Aggregation buckets with count per group, plus query metadata.

​
data
Data · object[]
required

List of aggregation buckets. Each bucket contains the grouping column value(s) and a 'count' key. Ordered by count DESC, or chronologically ASC when a date dimension is active. Null values in grouping columns appear as null in the bucket.

​
elapsed_ms
integer
required

Query execution time in milliseconds.

​
metadata
StatsMetadata · object
required