Fetch Series Data from External Providers

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.

curl -u YOUR_API_KEY: https://api.alphacast.io/providers/fred/series/UNRATE

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.

Provider series endpoints

GET /providers//series/

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

slug

string

required

Provider slug. Examples: fred, bls, worldbank, bcra, banxico.

series_id

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.

# 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

Response fields

series_id

string

required

The series identifier that was requested.

label

string

required

Descriptive name of the series as provided by the upstream source. Example: "Unemployment Rate".

metadata

object

required

Provider-specific metadata about the series. Contents vary by provider but may include frequency, units, seasonal adjustment, source, and notes.

data

object[]

required

Array of data points, most recent ~24 observations. Each item has:

Show data point properties

date

string

Observation date in YYYY-MM-DD format.

value

number | null

Numeric value for the observation. null when the upstream source reports a missing value.

is_preview

boolean

required

Always true for this endpoint. Indicates the data array is truncated to the most recent observations.

api_key_required

boolean

Present when the provider requires an upstream API key. Always true in that case.

has_api_key

boolean

Present when api_key_required is true. Whether you have a stored key for this provider.

api_key_hint

string

Present when api_key_required is true. Instructions for obtaining and saving an API key.

Example response

{
  "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:

{
  "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//series//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

slug

string

required

Provider slug.

series_id

string

required

Series identifier.

Request body

params

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"`

# 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"}}'

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

is_preview

boolean

required

Always false. The data array contains the complete historical series.

series_id

string

required

The requested series ID.

label

string

required

Descriptive name of the series.

metadata

object

required

Provider-specific metadata.

data

object[]

required

Complete array of all available observations, each with date (string, YYYY-MM-DD) and value (number or null).

Example response

{
  "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.

Find the right provider

curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/providers/match?q=federal+reserve+interest+rates"

Search for a series within the provider

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.

Preview the series

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.

Fetch the full history

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.

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/

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

query

string

required

Search term to look up in FRED. URL-encode spaces as %20 or +.

curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/search/consumer+price+index"

Response

{
  "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//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

symbol

string

required

FRED series symbol. Examples: GDP, UNRATE, CPIAUCSL, FEDFUNDS, DGS10.

Query parameters

$format

string

default:"csv"

Output format. Accepted values: json, csv, xlsx, tsv.

$top

number

Limit the number of rows returned. Omit to return all available data.

start

string

Start date filter in YYYY-MM-DD format.

end

string

End date filter in YYYY-MM-DD format.

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

{
  "error": "Provider does not support hierarchical browse"
}

​Authentication

​Provider series endpoints

​GET /providers//series/

​POST /providers//series//data

​Complete workflow example

​FRED direct endpoints

​GET /fred/search/

​GET /fred//data

​Error responses

Authentication

Provider series endpoints

GET /providers//series/

POST /providers//series//data

Complete workflow example

FRED direct endpoints

GET /fred/search/

GET /fred//data

Error responses