### POST /api/v4/{collection}/aggregate

**Count and summarise** (`aggregate`). Exact counts and metrics, optionally grouped by up to two fields (dates by year, quarter or month). Columns carry real names; the top 100 groups are returned.

1¢ per successful request. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | object |  |  |
| `group_by` | array<string \| object> |  | Up to two fields; dates as {"field":"announced_at","bucket":"quarter"}. Funding rounds can group by "investor"; exits by "acquirer". |
| `metrics` | array<"count" \| object> |  | Default ["count"]. Others: {"sum":"amount_usd"}, {"avg":…}, {"min":…}, {"max":…}, {"count_distinct":…}; add "as" to name the column. |
| `sort` | array<string> |  | Output column names; "-" for descending. Default: first metric descending. |
| `limit` | integer |  | Top groups to return, 1–100 (default 100). |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | The results. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |
| `meta.applied_filter` | object \| null | yes |  |
| `meta.records` | object | yes | Records matching the filter. |
| `meta.records.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `meta.records.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `meta.groups` | object | yes | Aggregates return the top groups; complete is false when groups were left out. |
| `meta.groups.returned` | integer | yes |  |
| `meta.groups.total` | integer | yes |  |
| `meta.groups.complete` | boolean | yes |  |
| `meta.groups_overlap` | boolean |  | true for tag or investor groupings: a record can be in several groups, so sums are not additive. |
| `meta.totals` | object |  | count and sum across all matching records (scalar groupings only). |
| `meta.match_scope` | string |  |  |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 400 | `OPERATOR_NOT_SUPPORTED` | The operator is not available for this field. |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. |
| 400 | `VALUE_AMBIGUOUS` | A friendly filter value matches several canonical values. |
| 400 | `QUERY_TOO_COMPLEX` | The filter exceeds the complexity limits. |
| 400 | `COLUMN_NAME_CONFLICT` | Two aggregate columns would have the same name. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/funding_rounds/aggregate' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "announced_at": {
        "gte": "-12m"
      }
    },
    "group_by": [
      "hq_country"
    ],
    "metrics": [
      "count",
      {
        "sum": "amount_usd",
        "as": "raised_usd"
      }
    ],
    "sort": [
      "-raised_usd"
    ],
    "limit": 5
  }'

```