GET /datasets/{id} — Get a Dataset

Retrieve a single dataset by numeric ID, including its name, repository, description, column schema, date range, and your permission level.

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

dataset_id · integer · required

The numeric ID of the dataset to retrieve.

Get dataset metadata

cURL

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

id · integer

Unique numeric identifier for the dataset.

name · string

Display name of the dataset.

repositoryId · integer

ID of the repository this dataset belongs to.

description · string

Optional human-readable description.

sourceName · string

Name of the original data source.

sourceUrl · string

URL linking to the original data source.

permission · string

Your permission level: Read, Write, or Admin.

frequency · string

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

minDate · string

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

maxDate · string

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

columns · array

Array of column definition objects describing the dataset schema.

Show column properties

id · integer

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

name · string

Column display name.

dataType · string

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

isEntity · 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

inferedFreq · string

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

minDate · string

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

maxDate · 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.