> ## Documentation Index
> Fetch the complete documentation index at: https://exa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> The Exa API is served at https://api.exa.ai. Authenticate with `Authorization: Bearer $EXA_API_KEY` (or `x-api-key: $EXA_API_KEY`); create keys at https://dashboard.exa.ai/api-keys.
> Prefer the official SDKs, `exa-py` (`pip install exa-py`) and `exa-js` (`npm install exa-js`); both read `EXA_API_KEY` from the environment.
> Tool-using agents can call Exa without writing code through the hosted MCP server at https://mcp.exa.ai/mcp, or install the Exa agent skill with `npx skills add exa-labs/agent-skills` (skill file: https://exa.ai/docs/skill.md).
> The OpenAPI specs at https://exa.ai/docs/exa-spec.yaml and https://exa.ai/docs/team-management-spec.yaml are the source of truth for request and response schemas.
# Macrobond
> Search and fetch macroeconomic and financial time series, entity metadata, and release calendars.
[Macrobond](https://www.macrobond.com) aggregates macroeconomic and financial
time series from central banks, statistical offices, and other primary sources
worldwide. [Exa Connect](/docs/agent/connect/overview) provides read-only access to
Macrobond's time-series catalog and data.
Attach `macrobond` to an [Exa Agent](/docs/agent/quickstart) run, and the agent
queries Macrobond alongside Exa web search.
## Use it for
* Finding the right series for an indicator (GDP, CPI, unemployment, policy rates) for a given country or region.
* Pulling recent observations for one or more series, with a cap on how many observations to return.
* Comparing series with different native frequencies or currencies on a shared calendar.
* Looking up a series' source, units, frequency, region, and date range without fetching data.
* Checking when an indicator is next scheduled to be published or revised.
## Provider ID
Use this value in `dataSources`:
```text theme={null}
macrobond
```
## Pricing
Macrobond tool calls currently carry no per-call provider charge: you pay only
the standard [Agent run pricing](/docs/agent/quickstart#pricing).
## Data available
| Data | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Series search | Free-text search over Macrobond's time-series catalog, optionally filtered by entity type or metadata attributes such as `Region` and `Frequency`. Returns metadata only. |
| Series observations | Dates and values plus metadata for up to 10 named series per call, keeping the most recent observations (100 by default, up to 2,000). |
| Unified series | Multiple series converted server-side to a shared frequency and optional currency, with aligned dates, for comparing series that differ natively. |
| Entity metadata | Full metadata for series, releases, regions, and sources: description, region, frequency, source, units, date range, and related entities. |
| Upcoming releases | Scheduled publication events for a release: expected and source release times, reference periods, and whether each event brings new or revised values. |
Macrobond entities have no public web URL. The agent identifies each series by its
Macrobond entity name (for example `usgdp` or `uscpi`), discovered through search,
and uses that name in every other Macrobond tool.
## Example
Compare US and euro-area headline inflation over the past two years and find the next US CPI release.
```python Python theme={null}
from exa_py import Exa
exa = Exa()
run = exa.agent.runs.create(
query=(
"Compare year-over-year headline CPI inflation in the US and the euro "
"area over the past two years, and tell me when the next US CPI "
"release is scheduled."
),
data_sources=[{"provider": "macrobond"}],
output_schema={
"type": "object",
"required": ["usLatest", "euroAreaLatest", "comparison", "nextUsCpiRelease"],
"properties": {
"usLatest": {"type": "number", "description": "latest US YoY CPI inflation, percent"},
"euroAreaLatest": {"type": "number", "description": "latest euro-area YoY CPI inflation, percent"},
"comparison": {"type": "string", "description": "how the two paths diverged over the past two years"},
"nextUsCpiRelease": {"type": "string", "description": "ISO 8601 timestamp of the next scheduled US CPI release"},
},
},
)
run = exa.agent.runs.poll_until_finished(run.id)
```
```typescript TypeScript theme={null}
import Exa from "exa-js";
const exa = new Exa();
const run = await exa.agent.runs.create({
query:
"Compare year-over-year headline CPI inflation in the US and the euro area over the past two years, and tell me when the next US CPI release is scheduled.",
dataSources: [{ provider: "macrobond" }],
outputSchema: {
type: "object",
required: ["usLatest", "euroAreaLatest", "comparison", "nextUsCpiRelease"],
properties: {
usLatest: { type: "number", description: "latest US YoY CPI inflation, percent" },
euroAreaLatest: { type: "number", description: "latest euro-area YoY CPI inflation, percent" },
comparison: { type: "string", description: "how the two paths diverged over the past two years" },
nextUsCpiRelease: { type: "string", description: "ISO 8601 timestamp of the next scheduled US CPI release" },
},
},
});
```
```bash cURL theme={null}
curl -s -X POST "https://api.exa.ai/agent/runs" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $EXA_API_KEY" \
-d '{
"query": "Compare year-over-year headline CPI inflation in the US and the euro area over the past two years, and tell me when the next US CPI release is scheduled.",
"dataSources": [{ "provider": "macrobond" }],
"outputSchema": {
"type": "object",
"required": ["usLatest", "euroAreaLatest", "comparison", "nextUsCpiRelease"],
"properties": {
"usLatest": { "type": "number", "description": "latest US YoY CPI inflation, percent" },
"euroAreaLatest": { "type": "number", "description": "latest euro-area YoY CPI inflation, percent" },
"comparison": { "type": "string", "description": "how the two paths diverged over the past two years" },
"nextUsCpiRelease": { "type": "string", "description": "ISO 8601 timestamp of the next scheduled US CPI release" }
}
}
}'
```
## Pairs well with
* [Exa web search](/docs/search/quickstart): add central-bank commentary and news context to the numbers.
* [Financial Datasets](/docs/agent/connect/financialdatasets): connect macro series to company prices, fundamentals, and filings.
* [Polymarket](/docs/agent/connect/polymarket): compare official data and release dates with market-implied expectations.
## Next steps
The Exa Connect quickstart covers `dataSources`, pricing, and the full partner catalog.
Attach up to five partners to one run and shape the query so each one fires.
Create runs, stream progress, design output schemas, and control effort and cost.
Create a key in the dashboard and run this page's example as-is. New accounts start with free credits.