GET /datasets/{id} — Get a Dataset

Use this endpoint to retrieve full metadata for a specific dataset, including its column definitions and date range. This is useful before downloading data, as it lets you inspect the available columns and verify you have the right dataset. A supplementary endpoint, GET /datasets/{id}/date-stats, returns precise frequency and date-range information computed directly from the stored data.

Authentication

Authenticate using HTTP Basic Auth. Pass your API key as the username and leave the password empty.

Endpoints

Method	URL	Description
`GET`	`/datasets/{dataset_id}`	Retrieve dataset metadata
`GET`	`/datasets/{dataset_id}/date-stats`	Retrieve inferred frequency and date range

Path parameters

integer

required

The numeric ID of the dataset to retrieve.

Get dataset metadata

curl -u YOUR_API_KEY: https://api.alphacast.io/datasets/123

import requests

response = requests.get(
    "https://api.alphacast.io/datasets/123",
    auth=("YOUR_API_KEY", ""),
)
dataset = response.json()

const response = await fetch("https://api.alphacast.io/datasets/123", {
  headers: { Authorization: "Basic " + btoa("YOUR_API_KEY:") },
});
const dataset = await response.json();

Response

integer

Unique numeric identifier for the dataset.

string

Display name of the dataset.

integer

ID of the repository this dataset belongs to.

string

Optional human-readable description.

string

Name of the original data source.

string

URL linking to the original data source.

string

Your permission level: Read, Write, or Admin.

string

Inferred data frequency (e.g., monthly, quarterly, daily). May be null if not yet computed.

string

Earliest date in the dataset (YYYY-MM-DD). May be null for empty datasets.

string

Latest date in the dataset (YYYY-MM-DD). May be null for empty datasets.

array

Array of column definition objects describing the dataset schema.

Show column properties

integer

Unique column ID. Use this value with $select to reference columns reliably across renames.

string

Column display name.

string

Data type of the column. One of Date, String, or Decimal.

boolean

When true, this column is a dimension or index column (e.g., Date, Country). When false, it is a value column.

Example response

{
  "id": 123,
  "name": "US GDP Quarterly",
  "repositoryId": 45,
  "description": "Quarterly US GDP figures from BEA",
  "sourceName": "Bureau of Economic Analysis",
  "sourceUrl": "https://www.bea.gov/data/gdp",
  "permission": "Admin",
  "frequency": "quarterly",
  "minDate": "1947-01-01",
  "maxDate": "2024-10-01",
  "columns": [
    { "id": 1, "name": "Date", "dataType": "Date", "isEntity": true },
    { "id": 2, "name": "Country", "dataType": "String", "isEntity": true },
    { "id": 3, "name": "GDP", "dataType": "Decimal", "isEntity": false }
  ]
}

Get date statistics

The /date-stats endpoint returns frequency and date range information computed live from the dataset’s stored data. If the dataset record already has a cached frequency, minDate, and maxDate, those cached values are returned immediately. Otherwise, the values are computed from the column data on demand.

curl -u YOUR_API_KEY: https://api.alphacast.io/datasets/123/date-stats

Response

string

The inferred data frequency, such as monthly, quarterly, or daily.

string

The earliest date found in the dataset (YYYY-MM-DD).

string

The latest date found in the dataset (YYYY-MM-DD).

Example response

{
  "inferedFreq": "quarterly",
  "minDate": "1947-01-01",
  "maxDate": "2024-10-01"
}

The /date-stats endpoint supports optional authentication. Public datasets can be queried without an API key, while private datasets require authentication.

Overview

Repositories

Datasets

Data Providers

GET /datasets/{id} — Get a Dataset

Authentication

Endpoints

Path parameters

Get dataset metadata

Response

Example response

Get date statistics

Response

Example response