# Bulk Endpoint

> Fan out a single endpoint across up to 100 symbols or ISINs in one request.

`POST https://api.bavest.co/v2/bulk`

Group: Bulk. Route id: `v2_bulk`. Included in: Growth.

## Description

Fan out a single endpoint across up to 100 symbols or ISINs in one request. Results are returned as an array in the same order as the input.

Provide exactly one of `symbols` or `isins`. The `params` object is merged into every invocation for shared parameters (e.g., currency, date range).

## 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

None.

## Request body

JSON, required. Bulk invocation request with symbols/ISINs, target endpoint, and optional shared parameters.

| Field | Type | Always present | Description |
|---|---|---|---|
| `symbols` | array of object | no | List of per-symbol parameter objects. Each object is merged with `params` and sent to the target endpoint. Provide exactly one of `symbols` or `isins`. |
| `symbols[].symbol` | string | yes | Ticker symbol. Example: `AAPL`. |
| `symbols[].currency` | string | no | Target currency (ISO 4217) |
| `isins` | array of object | no | List of per-ISIN parameter objects. Each object is merged with `params` and sent to the target endpoint. Provide exactly one of `symbols` or `isins`. |
| `isins[].isin` | string | yes | ISIN code. |
| `endpoint` | string | yes | Target endpoint key. Selects the endpoint used for each entry. market_cap returns equity, ETF or fund metrics according to the asset type. Returns the target metrics response with its metric names, units, currency, and pagination, selecting market_cap for equities and aum/fund_aum for funds by default. Fund AUM is not equity market capitalization. Use params.fields to override this selection and params.limit/offset to page it. dividends_history is an alias for dividend and etf_dividend and uses the dividend-history endpoint. One of `search`, `etf_country`, `etf_profile`, `etf_top_holdings`, `etf_top_sectors`, `etf_holdings`, `etf_sector`, `etf_metrics`, `fund_metrics`, `etf_dividend`, `crypto_price`, `dividend`, `stock_profile`, `stock_metric`, `balance_sheet`, `cash_flow`, `income_statement`, `financials_ttm`, `estimates_consensus`, `estimates_recommendations`, `dividends_history`, `news_stock`, `market_cap`. Example: `etf_profile`. |
| `params` | object | no | Additional parameters passed to every invocation. Merged with each symbol/ISIN entry. Use for shared parameters like date ranges. |

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | array of BulkResultItem | no |  |
| `data[].symbol` | string | no | Echoed back from the request entry. Example: `AAPL`. |
| `data[].isin` | string | no | Echoed back from the request entry. Example: `US0378331005`. |
| `data[].valid` | boolean | no | Present and `false` when the invocation failed. |
| `data[].error` | string | no | Error code (only on failure). Example: `LAMBDA_INVOCATION_FAILED`. |
| `data[].message` | string | no | Error detail (only on failure). |
| `meta` | ResponseMeta | no | Response metadata, including server-side processing time and resolved request parameters. Successful and error responses use the same metadata shape. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl -X POST 'https://api.bavest.co/v2/bulk' \
  -H "x-api-key: $BAVEST_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"symbols":[{"symbol":"BTCUSD"},{"symbol":"ETHUSD"}],"endpoint":"crypto_price","params":{}}'
```

## 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://docs.bavest.co/docs/v2_bulk
- OpenAPI: https://docs.bavest.co/openapi.json (YAML: https://docs.bavest.co/openapi.yaml)
- Authentication: https://docs.bavest.co/docs/authentication.md
- MCP server for AI agents: https://docs.bavest.co/docs/mcp.md
- All routes: https://docs.bavest.co/llms.txt
