> ## Documentation Index
> Fetch the complete documentation index at: https://alphacastio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Series Data from External Providers

> Preview or download complete time-series data from FRED, BLS, World Bank, OECD, IMF, BIS, ECB, Eurostat, and central banks across Latin America, Europe, and Asia using the Alphacast provider API.

Once you have found a series ID — through browsing, searching, or the popular series list — you can fetch its data in two steps: a lightweight preview that returns the most recent data points, followed by a full historical fetch. For FRED series, a dedicated shortcut endpoint is also available that bypasses the provider slug workflow.

## Authentication

All endpoints use HTTP Basic Auth. Pass your Alphacast API key as the username with an empty password.

```bash theme={null}
curl -u YOUR_API_KEY: https://api.alphacast.io/providers/fred/series/UNRATE
```

<Note>
  For providers that require an upstream API key (such as FRED or INEGI), save your key via `PUT /user-keys/{slug}` first. Alphacast applies it automatically on every series request.
</Note>

***

## Provider series endpoints

### GET /providers/{slug}/series/{series_id}

Returns a preview of the series: the last \~24 data points, the series label, and metadata. The response always includes `"is_preview": true` to signal that the data is truncated.

Use this endpoint to confirm you have the right series before fetching the full history.

**Path parameters**

<ParamField path="slug" type="string" required>
  Provider slug. Examples: `fred`, `bls`, `worldbank`, `bcra`, `banxico`.
</ParamField>

<ParamField path="series_id" type="string" required>
  The series identifier as recognized by the upstream provider. Format varies by provider — for example, `UNRATE` for FRED, `CUUR0000SA0` for BLS, or `NY.GDP.PCAP.CD` for World Bank.

  Some providers — notably SDMX-style sources (UNICEF, ECB, INSEE, BOI, FAOSTAT, Norges Bank) — use hierarchical IDs that contain forward slashes, such as `IMF/IFS/Q.US.NGDP_XDC`. Alphacast accepts these in the URL as-is; you do **not** need to URL-encode the `/` characters.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  # Flat ID
  curl -u YOUR_API_KEY: \
    https://api.alphacast.io/providers/fred/series/UNRATE

  # Hierarchical SDMX-style ID with slashes — passed through verbatim
  curl -u YOUR_API_KEY: \
    https://api.alphacast.io/providers/ecb/series/EXR/D.USD.EUR.SP00.A
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.alphacast.io/providers/fred/series/UNRATE",
      auth=("YOUR_API_KEY", ""),
  )
  preview = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.alphacast.io/providers/fred/series/UNRATE",
    { headers: { Authorization: "Basic " + btoa("YOUR_API_KEY:") } },
  );
  const preview = await response.json();
  ```
</RequestExample>

**Response fields**

<ResponseField name="series_id" type="string" required>
  The series identifier that was requested.
</ResponseField>

<ResponseField name="label" type="string" required>
  Descriptive name of the series as provided by the upstream source. Example: `"Unemployment Rate"`.
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Provider-specific metadata about the series. Contents vary by provider but may include frequency, units, seasonal adjustment, source, and notes.
</ResponseField>

<ResponseField name="data" type="object[]" required>
  Array of data points, most recent \~24 observations. Each item has:

  <Expandable title="data point properties">
    <ResponseField name="date" type="string">
      Observation date in `YYYY-MM-DD` format.
    </ResponseField>

    <ResponseField name="value" type="number | null">
      Numeric value for the observation. `null` when the upstream source reports a missing value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="is_preview" type="boolean" required>
  Always `true` for this endpoint. Indicates the data array is truncated to the most recent observations.
</ResponseField>

<ResponseField name="api_key_required" type="boolean">
  Present when the provider requires an upstream API key. Always `true` in that case.
</ResponseField>

<ResponseField name="has_api_key" type="boolean">
  Present when `api_key_required` is `true`. Whether you have a stored key for this provider.
</ResponseField>

<ResponseField name="api_key_hint" type="string">
  Present when `api_key_required` is `true`. Instructions for obtaining and saving an API key.
</ResponseField>

**Example response**

```json theme={null}
{
  "series_id": "UNRATE",
  "label": "Unemployment Rate",
  "metadata": {
    "frequency": "Monthly",
    "units": "Percent",
    "seasonal_adjustment": "Seasonally Adjusted",
    "last_updated": "2024-04-05"
  },
  "data": [
    {"date": "2024-03-01", "value": 3.8},
    {"date": "2024-02-01", "value": 3.9},
    {"date": "2024-01-01", "value": 3.7},
    {"date": "2023-12-01", "value": 3.7}
  ],
  "is_preview": true
}
```

**Handling api\_key\_required**

When a provider needs an upstream key and you have not stored one, the preview still returns recent data where possible, but includes the key status fields:

```json theme={null}
{
  "series_id": "GDP",
  "label": "Gross Domestic Product",
  "metadata": {"frequency": "Quarterly", "units": "Billions of Dollars"},
  "data": [{"date": "2024-01-01", "value": 27360.9}],
  "is_preview": true,
  "api_key_required": true,
  "has_api_key": false,
  "api_key_hint": "A FRED API key is required. Get one for free."
}
```

Store your key with `PUT /user-keys/fred` to remove the restriction.

***

### POST /providers/{slug}/series/{series_id}/data

Returns the full historical time series. This endpoint accepts provider-specific parameters in the request body to control units, frequency, date ranges, and other transformations.

**Path parameters**

<ParamField path="slug" type="string" required>
  Provider slug.
</ParamField>

<ParamField path="series_id" type="string" required>
  Series identifier.
</ParamField>

**Request body**

<ParamField body="params" type="object" default="{}">
  Provider-specific parameters. The available keys depend on the provider — consult the `parameters` array in `GET /providers/{slug}` for valid options.

  Common examples:

  | Provider   | Parameter key | Example value                    |
  | ---------- | ------------- | -------------------------------- |
  | FRED       | `units`       | `"pc1"` (% change from year ago) |
  | FRED       | `frequency`   | `"q"` (quarterly)                |
  | BLS        | `startyear`   | `2010`                           |
  | BLS        | `endyear`     | `2024`                           |
  | World Bank | `country`     | `"BR"`                           |
  | World Bank | `date_range`  | `"2000:2024"`                    |
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  # Fetch full FRED unemployment data, resampled to annual % change
  curl -u YOUR_API_KEY: \
    -X POST https://api.alphacast.io/providers/fred/series/UNRATE/data \
    -H "Content-Type: application/json" \
    -d '{"params": {"units": "pc1", "frequency": "a"}}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.alphacast.io/providers/fred/series/UNRATE/data",
      auth=("YOUR_API_KEY", ""),
      json={"params": {"units": "pc1", "frequency": "a"}},
  )
  series = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.alphacast.io/providers/fred/series/UNRATE/data",
    {
      method: "POST",
      headers: {
        Authorization: "Basic " + btoa("YOUR_API_KEY:"),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ params: { units: "pc1", frequency: "a" } }),
    },
  );
  const series = await response.json();
  ```
</RequestExample>

**Response fields**

The response has the same structure as the preview endpoint, with one difference:

<ResponseField name="is_preview" type="boolean" required>
  Always `false`. The `data` array contains the complete historical series.
</ResponseField>

<ResponseField name="series_id" type="string" required>
  The requested series ID.
</ResponseField>

<ResponseField name="label" type="string" required>
  Descriptive name of the series.
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Provider-specific metadata.
</ResponseField>

<ResponseField name="data" type="object[]" required>
  Complete array of all available observations, each with `date` (string, `YYYY-MM-DD`) and `value` (number or null).
</ResponseField>

**Example response**

```json theme={null}
{
  "series_id": "UNRATE",
  "label": "Unemployment Rate",
  "metadata": {
    "frequency": "Monthly",
    "units": "Percent",
    "seasonal_adjustment": "Seasonally Adjusted",
    "last_updated": "2024-04-05"
  },
  "data": [
    {"date": "1948-01-01", "value": 3.4},
    {"date": "1948-02-01", "value": 3.8},
    "...",
    {"date": "2024-03-01", "value": 3.8}
  ],
  "is_preview": false
}
```

***

## Complete workflow example

The following example shows the full sequence: match a provider, search for a series, preview it, then fetch the complete history.

<Steps>
  <Step title="Find the right provider">
    ```bash theme={null}
    curl -u YOUR_API_KEY: \
      "https://api.alphacast.io/providers/match?q=federal+reserve+interest+rates"
    ```
  </Step>

  <Step title="Search for a series within the provider">
    ```bash theme={null}
    curl -u YOUR_API_KEY: \
      "https://api.alphacast.io/providers/fred/search?q=federal+funds+rate"
    ```

    Note the `id` from the results — for example, `FEDFUNDS`.
  </Step>

  <Step title="Preview the series">
    ```bash theme={null}
    curl -u YOUR_API_KEY: \
      https://api.alphacast.io/providers/fred/series/FEDFUNDS
    ```

    Check that `label` and `metadata` match what you expect. Confirm `is_preview: true`.
  </Step>

  <Step title="Fetch the full history">
    ```bash theme={null}
    curl -u YOUR_API_KEY: \
      -X POST https://api.alphacast.io/providers/fred/series/FEDFUNDS/data \
      -H "Content-Type: application/json" \
      -d '{"params": {"frequency": "m"}}'
    ```

    The response contains the complete monthly series with `is_preview: false`.
  </Step>
</Steps>

***

## FRED direct endpoints

These endpoints provide a streamlined interface to FRED without the provider slug workflow. They are useful when you already know your FRED symbol.

### GET /fred/search/{query}

Searches FRED for series matching the query string and returns matching symbols and descriptions.

**Path parameters**

<ParamField path="query" type="string" required>
  Search term to look up in FRED. URL-encode spaces as `%20` or `+`.
</ParamField>

```bash theme={null}
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/search/consumer+price+index"
```

**Response**

```json theme={null}
{
  "results": [
    {
      "id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100"
    }
  ]
}
```

***

### GET /fred/{symbol}/data

Fetches time-series data for a FRED symbol directly. Returns data as CSV by default; use `$format=json` for a JSON response.

**Path parameters**

<ParamField path="symbol" type="string" required>
  FRED series symbol. Examples: `GDP`, `UNRATE`, `CPIAUCSL`, `FEDFUNDS`, `DGS10`.
</ParamField>

**Query parameters**

<ParamField query="$format" type="string" default="csv">
  Output format. Accepted values: `json`, `csv`, `xlsx`, `tsv`.
</ParamField>

<ParamField query="$top" type="number">
  Limit the number of rows returned. Omit to return all available data.
</ParamField>

<ParamField query="start" type="string">
  Start date filter in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="end" type="string">
  End date filter in `YYYY-MM-DD` format.
</ParamField>

```bash theme={null}
# Get CPIAUCSL as JSON, last 5 rows
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/CPIAUCSL/data?$format=json&$top=5"

# Get data between two dates
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/GDP/data?$format=json&start=2020-01-01&end=2023-12-31"
```

***

## Error responses

All endpoints return a JSON error object with an `error` field when a request fails.

| Status | Meaning                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | The provider does not support the requested operation (e.g., browse on a non-hierarchical provider). |
| `404`  | Provider slug or series ID not found.                                                                |
| `501`  | The connector does not implement this operation.                                                     |
| `502`  | The upstream provider returned an error. Check the `error` message for details.                      |

```json theme={null}
{
  "error": "Provider does not support hierarchical browse"
}
```