# Security Search Aggregated

> Returns aggregated search results grouped by security type.

`GET https://api.bavest.co/v2/reference/search/aggregated`

Group: Reference. Route id: `v2_reference_search_aggregated`. Included in: Growth.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string | yes | Search query (name, ticker, or ISIN) Example `Tesla`. |
| `limit` | query | integer (int32) | no | Maximum number of results to return (default 100, max 1000) Default `100`. |
| `offset` | query | integer (int32) | no | Number of results to skip for pagination (default 0) Default `0`. |
| `cursor` | query | string | no | Opaque cursor for cursor-based pagination. When provided, returns results after the cursor position. Takes precedence over offset. |

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | object | no |  |
| `data.results` | array of object | no |  |
| `data.results[].name` | string | no | Security name. |
| `data.results[].listings` | array of SearchResult | no |  |
| `data.results[].listings[].symbol` | string | yes | Ticker symbol. Example: `AAPL`. |
| `data.results[].listings[].type` | string | yes | Asset class of the security (e.g. EQUITY, ETF, ETP, MUTUAL_FUND, CLOSED_END_FUND, BOND, ADR, INDEX, CRYPTO_CURRENCY, CURRENCY, COMMODITY, CERTIFICATE). `EQUITY` und `STOCK` sind im Bestand beide vergeben und meinen dasselbe; die Suche vereinheitlicht sie zu `EQUITY` und stellt das urspruengliche `STOCK` in `subtype`. Example: `EQUITY`. |
| `data.results[].listings[].subtype` | string \| null | no | Feinere Klassifizierung, sofern vorhanden. Traegt unter anderem das urspruengliche `STOCK`, wenn `type` zu `EQUITY` vereinheitlicht wurde. `null`, wenn keine feinere Angabe vorliegt. Example: `STOCK`. |
| `data.results[].listings[].exchange` | string \| null | no | Primary listing exchange. `null`, wenn zu dem Papier keine Boerse gefuehrt wird, etwa bei OTC-Anleihen ohne Handelsplatz. Example: `NASDAQ`. |
| `data.results[].listings[].isin` | string \| null | no | ISIN code (if available) Example: `US0378331005`. |
| `data.results[].listings[].companyName` | string | no | Full company name. Example: `Leverage Shares 3x Apple ETC`. |
| `data.results[].listings[].isActivelyTrading` | boolean \| null | no | Whether the security is actively trading. `null`, wenn die Quelle dazu nichts sagt; das betrifft vor allem Publikumsfonds, fuer die kein Handelsstatus gefuehrt wird (z. B. LU0327386487). Example: `true`. |
| `data.results[].listings[].isAdr` | boolean | no | Whether the security is an American Depositary Receipt. Example: `false`. |
| `data.results[].listings[].isEtf` | boolean | no | Whether the security is an ETF. Example: `true`. |
| `data.results[].listings[].isFund` | boolean | no | Whether the security is a fund. Example: `false`. |
| `data.results[].listings[].isReit` | boolean \| null | no | Whether the company is a REIT (real estate investment trust): its industry starts with "REIT", e.g. Realty Income "REIT - Retail". Never true for ETFs or funds. `null` when no industry is known. Example: `false`. |
| `data.results[].root_ticker` | string | no | Primary ticker symbol. |
| `meta` | ResponseMeta | no | Response metadata for paginated endpoints. Offset pagination returns `page`/`pageSize`/`totalPages`/`totalCount`; cursor pagination returns `pageSize`/`hasMore`/`nextCursor` and `totalCount` only when known. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |
| `meta.page` | integer | no | Current page number (offset pagination) Example: `1`. |
| `meta.pageSize` | integer | no | Number of results per page. Example: `50`. |
| `meta.totalPages` | integer | no | Total number of pages (offset pagination) Example: `2`. |
| `meta.totalCount` | integer | no | Total number of results across all pages. Example: `100`. |
| `meta.hasMore` | boolean | no | Whether more results follow (cursor pagination) |
| `meta.nextCursor` | string \| null | no | Cursor for the next page (cursor pagination), null on the last page. |

## Example request

```bash
curl 'https://api.bavest.co/v2/reference/search/aggregated?q=Tesla' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "results": [
      {
        "name": "Tesla, Inc.",
        "listings": [
          {
            "symbol": "TL0.DE",
            "isin": "US88160R1014",
            "exchange": "XETRA",
            "type": "ADR",
            "isEtf": false,
            "isAdr": true,
            "isFund": false
          },
          {
            "symbol": "TSLA",
            "isin": "US88160R1014",
            "exchange": "NASDAQ",
            "type": "EQUITY",
            "isEtf": false,
            "isAdr": false,
            "isFund": false
          }
        ],
        "root_ticker": "TSLA"
      },
      {
        "name": "Tesla Exploration Ltd.",
        "listings": [
          {
            "symbol": "TXLZF",
            "isin": "CA8816011081",
            "exchange": "PNK",
            "type": "EQUITY",
            "isEtf": false,
            "isAdr": false,
            "isFund": false
          }
        ],
        "root_ticker": "TXLZF"
      }
    ]
  },
  "meta": {
    "page": 1,
    "pageSize": 100,
    "totalPages": 1,
    "totalCount": 45,
    "parameters": {
      "limit": "100",
      "q": "Tesla"
    },
    "time": 198
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive). |
| 401 | Missing or invalid API key. |
| 404 | Resource not found. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_reference_search_aggregated
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt