API Headers: Request and Response

When you interact with the algoseek Datasets API, the server uses HTTP headers to manage authentication, control data delivery, and provide critical metadata about your requests. Understanding these headers is essential for building robust, scalable applications that can handle large financial datasets.

Request Headers#

Request header requirements are straightforward because the API primarily uses query parameters for content negotiation and routing.

Authentication#

X-API-KEY (Required): This is the primary mechanism for authenticating with the server. Every request must include this header with a valid API key. If missing or invalid, the server will reject the request with a 403 Forbidden error.

Example:

X-API-KEY: YOUR_API_KEY

A Note on Formatting#

Unlike many REST APIs that use the Accept header to negotiate response formats, this API uses the response_format query parameter (e.g., ?response_format=json or ?response_format=csv_gzip) to explicitly control the output.

Response Headers#

The server returns hidden metadata in the form of HTTP response headers to help your client application manage large datasets and track request status.

Pagination Headers#

Financial datasets often contain millions of records. To manage these, endpoints support pagination via offset and limit query parameters, tracked through these headers:

• X-Pagination-Offset: Confirms the number of records skipped before the current batch.
• X-Pagination-Limit: Confirms the maximum number of records returned in the current response.
• X-Pagination-Next-Offset: Confirms the number of records to skip to fetch the next page. This will be null if there are no more pages.
• Link: Provides the exact URL for the next page of data using the rel="next" attribute.

Request Tracing and Support#

X-Request-ID: A unique identifier (UUID) assigned to every API call. If you encounter validation errors or unexpected data gaps, provide this ID to algoseek support so engineers can quickly locate your transaction in the server logs.

Data Downloads#

Content-Disposition: Used when requesting compressed formats like csv_gzip. It tells your browser or client to treat the response as a downloadable attachment and provides a suggested filename (e.g., filename="us_equity_taq_AAPL_2024-01-15.csv.gz").

Rate Limiting Headers#

When your account approaches its usage limits, the API may include rate-limiting information in its responses. If you exceed your quota and receive a 429 Too Many Requests error, check these headers:

• X-RateLimit-Limit: The total configured quota for the resource you are accessing.
• X-RateLimit-Remaining: The number of requests remaining in the current window (this will be 0 when a request is rejected).