Alphacast Python SDK

Install the Alphacast Python SDK and interact with repositories, datasets, series, and search from your Python code — no need to call the REST API directly.

The Alphacast Python SDK is the official Python client for the Alphacast API. It wraps the REST endpoints in a small set of Python classes so you can manage repositories, upload and download datasets, query individual series, and search for content without writing HTTP code by hand.

The SDK is designed for the most common workflows of Alphacast users:

• Pulling data into a notebook — return any dataset directly as a pandas.DataFrame.
• Pushing your own data — upload a DataFrame or CSV with one method call.
• Automating data pipelines — create repositories, initialize columns, and check process status programmatically.
• Discovery — search datasets across your repositories or the entire public catalog.

The SDK is open source and published on PyPI as alphacast. Source code, issues, and releases live at github.com/Alphacastio/alphacast-python-sdk.

Installation

Install the package from PyPI:

pip install alphacast

The SDK targets Python 3.6+ and depends on requests, pandas, and python-dotenv. These are installed automatically.

Initialize the client

Import the Alphacast class and instantiate it with your API key. You can find your key in your account settings under Account Settings → API Key.

from alphacast import Alphacast

alphacast = Alphacast("YOUR_API_KEY")

The constructor returns a single client object that exposes four sub-clients — one per resource type:

Attribute	Class	Description
alphacast.repository	Repository	Create, list, and delete repositories.
alphacast.datasets	Datasets	List, create, upload, download, and delete datasets.
alphacast.search	Search	Full-text search for datasets across the catalog.
alphacast.series(id)	Series	Read metadata and data for a single series.

Avoid hardcoding your API key. Read it from an environment variable instead:

import os
from alphacast import Alphacast

alphacast = Alphacast(os.environ["ALPHACAST_API_KEY"])

The SDK also imports python-dotenv as a dependency — load a .env file with from dotenv import load_dotenv; load_dotenv() before reading the variable.

What’s in this section

Quickstart

End-to-end example: install, create a repository, upload a CSV, and download it as a DataFrame.

Authentication

Where to find your API key and how the SDK uses it.

Repositories

repository.read_all, read_by_id, read_by_name, create, delete.

Datasets

Find datasets by name or ID and inspect their metadata, columns, and date stats.

Uploading data

Create a dataset, initialize its columns, and upload from a DataFrame or CSV.

Downloading data

Pull data as JSON, CSV, XLSX, or directly into a pandas.DataFrame.

Series

Read metadata and data for individual series by ID.

Search

Search datasets across your repositories and Alphacast’s public catalog.

Beyond the SDK

The SDK does not currently cover every endpoint exposed by the REST API (data providers, MCP, account management). For workflows that fall outside the SDK’s surface, fall back to the REST API reference and call the API with requests directly using your same API key.