Understanding the algoseek API Dataset Schema

This tutorial explains the URL Path Architecture for the algoseek Datasets API. Unlike fixed-endpoint APIs, algoseek uses a hierarchical RESTful structure where the URL path is defined by Granularity (Data Type) of the dataset you are accessing. Understanding this structure will allow you to programmatically navigate the API, dynamically build queries, and efficiently extract the exact slices of market data your workflows require.

The Base URL Pattern

Every data request follows this fundamental structure, using the base URL (https://api.algoseek.com):

https://api.algoseek.com/v1/data/{group-name}/{dataset-name}/{path-parameters}

• {group-name}: The broad market category (e.g., us-equity, us-futures).
• {dataset-name}: The specific dataset family identifier (e.g., taq, daily-ohlc).
• {path-parameters}: Variable components required directly in the URL path for high-density datasets (e.g., specific dates or tickers).
• Query Parameters: Advanced filtering, sorting, and pagination logic (e.g., limit=10), which are passed as URL queries or via --data when using curl --get.

Path Structures by Data Type

The structure of the URL depends heavily on how the data is partitioned. Higher-granularity data requires specific path parameters to ensure optimal database routing, while lower-granularity reference data uses query strings for flexible filtering.

Tick and Trade Data (Highest Granularity)

For datasets with millions of records per day per symbol, the API requires both the trade_date and identifier to be explicitly declared in the URL path.

• Pattern: .../{group-name}/{dataset-name}/{trade_date}/{identifier}
• Used for: Trade and Quote (TAQ), Trade-Only Tick, Trade and NBBO Quotes, etc.

Ticker vs. ASID: Identifier Architecture

Currently, our API supports two types of identifiers to represent a security: Ticker and ASID (Algoseek Security Identifier):

• Ticker (e.g, Ticker=AAPL)

A ticker is the exchange-listed symbol used for market data and trading. Because companies can change their ticker after a rebranding or corporate action, and exchanges may later assign the same ticker to another company, a ticker should not be treated as a permanent one.

• ASID (e.g, ASID=1010000000001033)

ASID is Algoseek's permanent internal security identifier. It remains unchanged throughout a company's lifetime, regardless of ticker changes or other corporate actions, making it the recommended identifier for historical analysis, database relationships, and long-term data consistency.

Feature	Ticker	ASID
Persistence	Volatile	Immutable
Primary Use	Market Data/Execution	Relational Storage/Analytics
Scope	Exchange-specific	Entity-specific

Implementation: The FB/META Conflict

The mapping below shows how ASID preserves the identity of a company even when its ticker changes.

Example Request:

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/secid-chains-lookup' \
     --data-urlencode 'Ticker.in=FB,META' \
     -H "X-API-KEY: YOUR_API_KEY"

Example Output:

[
  { "ASID": 1010000000011779, "Ticker": "FB", "StartDate": "2012-05-18", "EndDate": "2022-06-08" },
  { "ASID": 1010000000011782, "Ticker": "META", "StartDate": "2021-06-30", "EndDate": "2022-01-28" },
  { "ASID": 1010000000011779, "Ticker": "META", "StartDate": "2022-06-09", "EndDate": "2149-06-06" },
  { "ASID": 1010000000027827, "Ticker": "FB", "StartDate": "2025-06-26", "EndDate": "2149-06-06" }
]

Facebook changed its ticker from FB to META in 2022 while retaining the same ASID. When the ticker FB was later assigned to another company, a new ASID was created. This separation prevents unrelated companies from sharing the same historical records and preserves data integrity when tickers are reused.

Important Note

Some tickers are exchange test symbols, not real listed securities, and therefore have no corresponding entity to key off — no ASID/SecId is assigned, e.g., ATEST.A (Nasdaq test symbol), IBO (CTA/UTP test symbol), etc.

Such symbols exist purely for infrastructure testing. They have no underlying company, no corporate actions, and no persistent identity to track — so they fall outside the Ticker/ASID mapping schema entirely and should be filtered out of any entity-level analytics.

Example Request:

curl --get \
     'https://api.algoseek.com/v1/data/us-equity/taq/2023-08-02/AAPL' \
     --data-urlencode 'limit=10' \
     -H "X-API-KEY: YOUR_API_KEY"

curl --get \
     'https://api.algoseek.com/v1/data/us-equity/taq/2023-08-02/1010000000001033' \
     --data-urlencode 'limit=10' \
     -H "X-API-KEY: YOUR_API_KEY"

Example Output:

{
    "data": [
        {
            "TradeDate": "2023-08-02",
            "EventDateTime": "2023-08-02 03:59:00.019011167",
            "EventType": "QUOTE BID",
            "Ticker": "AAPL",
            "ASID": 1010000000001033,
            "Price": 0,
            "Quantity": 0,
            "Exchange": "BATS",
            "ConditionCode": 8
        },
...
    ],
    "pagination": {
        "offset": 0,
        "limit": 10,
        "next_offset": 10
    }
}

Intraday Bar and Daily Data

Both intraday bars (e.g., 1-minute or 1-second aggregates) and daily end-of-day data share the same URL structure. They partition by identifier directly in the path, while dates and other filters are handled via query parameters.

• Pattern: .../{group-name}/{dataset-name}/{identifier}
• Used for: 1-minute TAQ bars, Trade-Only minute bars, extended minute bars, Daily OHLC, Daily TAQ analytics, and Options Daily Greeks.

Timespan Limits

The period query parameter limits how much historical data is returned relative to the current or specified date. It defines a rolling lookback window and is supported by all endpoints where the trade date is not a path parameter (Daily, Bars). You can query the period of data by using the Y, W, and D units:

• period=5D (5 days)
• period=1W (1 week)
• period=7Y (7 years)

To optimize the response time, we use the following period defaults:

• period=5Y - 5 years for smaller datasets (trade-only minute bars, daily data, or reference data)
• period=1Y - 1 year for heavy datasets (trade and quote extended bars)

Example A: Fetch last 2 days of Equity Trade and Quote Minute Bar

curl --get \
     'https://api.algoseek.com/v1/data/us-equity/taq-1min/AAPL' \
     --data-urlencode 'period=2D' \
     -H "X-API-KEY: YOUR_API_KEY"

Note on Data Volume

While we support requests for long-term history (e.g., 20Y), executing queries against large datasets may result in increased latency or request timeouts. We recommend using smaller periods or specific TradeDate filters for high-frequency data applications.

Usage of the period parameter with filtering logic

The period parameter dictates the maximum allowed time window for a request. But interaction with date column filters is governed by the following rules:

• Dual Filters (e.g TradeDate.gt AND TradeDate.lt). If the range between the filters is less than or equal to the specified period (e.g, TradeDate.gt=2020-03-03 AND TradeDate.lt=2021-03-03 AND period=2Y), the request is processed.

Example B: Fetch the 2 weeks of Equity Daily OHLC within the date range

curl --get \
     'https://api.algoseek.com/v1/data/us-equity/daily-ohlc/AAPL' \
     --data-urlencode 'TradeDate.gt=2020-03-03' \
     --data-urlencode 'TradeDate.lt=2020-03-07' \
     --data-urlencode 'period=2W' \
     -H "X-API-KEY: YOUR_API_KEY"

Output:

{
    "data": [
        {
            "TradeDate": "2020-03-04",
            "Ticker": "AAPL",
            "ASID": 1010000000001033,
            "OpenPrice": 296.8,
            "HighPrice": 303.4,
            "LowPrice": 293.13,
            "ClosePrice": 302.74,
            "MarketHoursVolume": 52453340,
            "MarketHoursFinraVolume": 21265845,
            "DailyVolume": 55234261,
            "DailyFinraVolume": 22710925,
            "MarketHoursVWAP": 298.1866,
            "DailyVWAP": 298.2695
        },
...       
    ],
    "pagination": {
        "offset": 0,
        "limit": 1000,
        "next_offset": null
    }
}

But if the range exceeds the provided period parameter, then you will receive the 422 Unprocessable Entity error.

curl --get \
     'https://api.algoseek.com/v1/data/us-equity/daily-ohlc/AAPL' \
     --data-urlencode 'TradeDate.gt=2020-03-03' \
     --data-urlencode 'TradeDate.lt=2021-03-03' \
     --data-urlencode 'period=5W' \
     -H "X-API-KEY: YOUR_API_KEY"

Output:

{
    "detail": [
        {
            "msg": "The date range between the provided date filters on 'TradeDate' exceeds the history limit of 2 days",
            "type": "value_error",
            "loc": [
                "query",
                "TradeDate"
            ],
            "input": ""
        }
    ]
}

• Single Filter (TradeDate.gt OR TradeDate.lt): If only one Date filter is provided, the API returns data for a period-sized date range anchored to the specified date, where TradeDate.gt is the start of the range and TradeDate.lt - the specified date is the end of the range.

Example D: Fetch the 10 years of Equity Daily OHLC data before 2024.

curl --get \
     'https://api.algoseek.com/v1/data/us-equity/daily-ohlc/AAPL' \
     --data-urlencode 'TradeDate.lt=2024-01-01' \
     --data-urlencode 'period=10Y' \
     -H "X-API-KEY: YOUR_API_KEY"

Output:

{
    "data": [
        {
            "TradeDate": "2014-01-03",
            "Ticker": "AAPL",
            "ASID": 1010000000001033,
            "OpenPrice": 553,
            "HighPrice": 553.68,
            "LowPrice": 540.43,
            "ClosePrice": 540.98,
            "MarketHoursVolume": 13639055,
            "MarketHoursFinraVolume": 5262478,
            "DailyVolume": 14035742,
            "DailyFinraVolume": 5369053,
            "MarketHoursVWAP": 545.3396,
            "DailyVWAP": 545.3001
        },
...
    ],
    "pagination": {
        "offset": 0,
        "limit": 1000,
        "next_offset": 1000
    }
}

Reference Data

Reference data helps you build out your security masters and historical universes. Because it tracks lifecycle events, lookups, and static info, there are no path parameters. Filtering depends entirely on query parameters (e.g., Ticker, SecId, ASID, StartDate).

• Pattern: .../{group-name}/{dataset-name}

• Used for: Security Master, Ticker/FIGI Lookups, ASID chains, IPO Details, Shares Outstanding.

• Example: GET /v1/data/us-equity-ref/sec-master

• Used for: OHLC, Security Master, Dividends, Splits, and IPO data.

curl --get \
     'https://api.algoseek.com/v1/data/us-equity-ref/sec-master' \
     --data-urlencode 'SecId=2234' \
     --data-urlencode 'limit=10' \
     -H "X-API-KEY: YOUR_API_KEY"

Example Output:

{
    "data": [
        {
            "SecId": 2234,
            "ASID": 1010000000016306,
            "ListStatus": "L",
            "SecurityDescription": "Equity Shares",
            "Sic": 6311,
            "Sector": "Finance Insurance And Real Estate",
            "Industry": "Life Insurance",
            "SEDOL": "2568283",
            "Ticker": [
                "SLF"
            ],
            "TickerStartToEndDate": [
                "20070103:29991231"
            ],
            "Name": [
                "Sun Life Financial, Inc."
            ],
            "NameStartToEndDate": [
                "20070103:29991231"
            ],
            "ISIN": [
                "CA8667961053"
            ],
            "ISINStartToEndDate": [
                "20070103:29991231"
            ],
            "USIdentifier": [
                "866796105"
            ],
            "USIdentifierStartToEndDate": [
                "20070103:29991231"
            ],
            "PrimaryExchange": [
                "NYSE"
            ],
            "PrimaryExchangeStartToEndDate": [
                "20070103:29991231"
            ],
            "FIGI": [
                "BBG000LRMSB8"
            ]
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 10,
        "next_offset": null
    }
}

Common Data Groups

When constructing your URL, use the exact asset class prefix defined in the API:

Asset Class Segment	Prefix	Description
US Equities	us-equity	Market data for stocks, ETFs, ETNs, and ADRs.
US Equity Options	us-equity-opt	OPRA options trades, quotes, bars, and daily Greeks.
US Futures	us-futures	Futures market data across CME, CBOT, COMEX, and NYMEX.
Equity Reference	us-equity-ref	Masters, corporate actions, fundamentals, and events.
Options Reference	us-equity-opt-ref	Options security masters and OCC settlement data.

URL Logic

Data Type	Path Structure	Standard Filtering Method
Tick / L1	{dataset}/{trade_date}/{identifier}	Path parameters restrict the date and symbol completely.
Intraday Bars	{dataset}/{identifier}	Path restricts symbol; Query restricts TradeDate.
Daily Bars	{dataset}/{identifier}	Path restricts symbol; Query restricts TradeDate.
Reference	{dataset}	Highly variable. Query filters by Ticker, SecId, ASID, or Date ranges.

Note on URL Logic

You can use any other column as an additional filter, provided that the column is not already being used as a primary query parameter (e.g., you cannot add a secondary filter for TradeDate on Intraday Bars).

Discovering the URL and Filters

If you are unsure of the path structure or the exact column names available for advanced filtering on a specific dataset, use the Metadata Endpoints:

• GET /v1/meta/datasets to list all datasets.
• GET /v1/meta/datasets/{dataset_id}/columns to see every column you can query against.