Skip to main content
A series is a single time-indexed variable inside a dataset — for example, the headline CPI of a single country. Series are addressable by ID across all of Alphacast, so you can pull them directly without going through their parent dataset. The SDK exposes series via alphacast.series(series_id), which returns a Series handle. 
from alphacast import Alphacast

alphacast = Alphacast("YOUR_API_KEY")
series = alphacast.series(12345)
You need read permission on the parent dataset to read a series. Find a series ID in the URL on alphacast.io when viewing an individual variable.

​
Read metadata

meta = alphacast.series(12345).metadata()
print(meta)
Returns a dict describing the series — its name, dataset ID, units, frequency, and other metadata fields exposed by the REST API.

​
Download the data

Like datasets, series support the same five output formats: 
# pandas
df = alphacast.series(12345).download_data(format="pandas")

# csv bytes
csv_bytes = alphacast.series(12345).download_data("csv")

# json (list of dicts)
rows = alphacast.series(12345).download_data(format="json")

# xlsx / tsv bytes
xlsx_bytes = alphacast.series(12345).download_data("xlsx")
tsv_bytes = alphacast.series(12345).download_data("tsv")
When format="pandas", the SDK fetches CSV under the hood and returns a parsed DataFrame. When format="json", the SDK parses newline-delimited JSON and returns a list of dicts.
The Series download endpoint does not currently expose date-range or column filters. If you need filtered reads, fetch from the parent dataset with download_data instead.

​
Method signature

class Series:
    def metadata(self) -> dict: ...
    def download_data(self, format: str = "csv"): ...
​
format
str
default:"\"csv\""
One of "csv", "json", "xlsx", "tsv", or "pandas". The first four return raw bytes (or list of dicts for JSON); "pandas" returns a DataFrame.

​
When to use series vs datasets

  • Series — ideal when you only need a single variable, and you already know its series ID. Lighter payload, single-column DataFrame.
  • Dataset — ideal when you need multiple variables together, want to filter by entity or date, or want to manage uploads. Use download_data on the dataset handle.

​
Next steps

  • Find dataset and series content with Search.
  • Combine multiple variables in a single download via Downloading data.