Getting Started

This guide walks you through making your first request to the Historical Market Data API.

Base URL

https://algo.pocketful.in

Replace https://algo.pocketful.in with your production API endpoint.

Authentication

Every request must include a valid API token in the Authorization header.

Authorization: Bearer YOUR_ACCESS_TOKEN

Authorization: YOUR_ACCESS_TOKEN

Supported Product Types

Product Type	Description
`futures`	Futures Contracts
`options`	Options Contracts

Supported Intervals

Interval
`1minute`
`3minute`
`5minute`
`10minute`
`15minute`
`30minute`
`60minute`
`1day`

Example 1 — Fetch Futures Historical Data

Endpoint

POST /api/data/v1/historical

Request Body

{
    "symbol": "BANKNIFTY",
    "product_type": "futures",
    "expiry_date": "2025-01-29",
    "interval": "1minute",
    "from_date": "2025-01-01T09:15:00",
    "to_date": "2025-01-01T15:30:00"
}

cURL

curl --request POST \
--url https://algo.pocketful.in/api/data/v1/historical \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "symbol":"BANKNIFTY",
    "product_type":"futures",
    "expiry_date":"2025-01-29",
    "interval":"1minute",
    "from_date":"2025-01-01T09:15:00",
    "to_date":"2025-01-01T15:30:00"
}'

Example 2 — Fetch Call Option Historical Data

Endpoint

POST /api/data/v1/historical

Request Body

{
    "symbol": "BANKNIFTY",
    "product_type": "options",
    "type": "CE",
    "strike_price": 51000,
    "expiry_date": "2025-01-29",
    "interval": "1minute",
    "from_date": "2025-01-01T09:15:00",
    "to_date": "2025-01-01T15:30:00"
}

cURL

curl --request POST \
--url https://algo.pocketful.in/api/data/v1/historical \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "symbol": "BANKNIFTY",
    "product_type": "options",
    "type": "CE",
    "strike_price": 51000,
    "expiry_date": "2025-01-29",
    "interval": "1minute",
    "from_date": "2025-01-01T09:15:00",
    "to_date": "2025-01-01T15:30:00"
}'

Example 3 — Fetch Put Option Historical Data

Endpoint

POST /api/data/v1/historical

Request Body

{
    "symbol": "BANKNIFTY",
    "product_type": "options",
    "type": "PE",
    "strike_price": 51000,
    "expiry_date": "2025-01-29",
    "interval": "1minute",
    "from_date": "2025-01-01T09:15:00",
    "to_date": "2025-01-01T15:30:00"
}

cURL

curl --request POST \
--url https://algo.pocketful.in/api/data/v1/historical \
--header "Authorization: Bearer YOUR_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "symbol": "BANKNIFTY",
    "product_type": "options",
    "type": "PE",
    "strike_price": 51000,
    "expiry_date": "2025-01-29",
    "interval": "1minute",
    "from_date": "2025-01-01T09:15:00",
    "to_date": "2025-01-01T15:30:00"
}'

Successful Response

{
    "status": "success",
    "data": [
        {
            "timestamp": "2025-01-01T09:15:00Z",
            "open": 51200.50,
            "high": 51350.25,
            "low": 51180.00,
            "close": 51300.10,
            "volume": 125400,
            "open_interest": 10842000
        }
    ]
}

Required Parameters

Parameter	Type	Required	Description
`symbol`	String	✅	Trading symbol (e.g. NIFTY, BANKNIFTY)
`product_type`	String	✅	`futures` or `options`
`type`	String	Required for Options	`CE` (Call) or `PE` (Put)
`expiry_date`	Date	✅	Contract expiry date
`strike_price`	Number	Required for Options	Strike price for options contracts
`interval`	String	✅	Candle interval
`from_date`	DateTime	✅	Start date and time
`to_date`	DateTime	✅	End date and time

!!! note

The `strike_price` and `type` fields are **required only** when `product_type` is `options`. They are **not required** for `futures`.

Next Steps

Read the Authentication guide.
Explore the Historical Data API Reference.
Learn about the Export API for large historical data requests.
Review the Error Codes and Troubleshooting sections.

3. Check Export Status

Retrieve the current status of an asynchronous export job. Once the export is complete, the API returns a pre-signed download URL for the generated CSV file.

Endpoint

GET /api/data/v1/status/:job_id

Path Parameters

Parameter	Type	Required	Description
`job_id`	UUID	Yes	The unique identifier returned when the export job was created.

Example Request

curl --request GET \
  --url https://algo.pocketful.in/api/data/v1/status/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Response (Processing)

{
  "status": "success",
  "job": {
    "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "processing",
    "request": {
      "...": "..."
    },
    "created_at": "2026-06-29T09:49:10Z"
  }
}

Response (Completed)

{
  "status": "success",
  "job": {
    "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "completed",
    "request": {
      "...": "..."
    },
    "file_url": "https://pktl-market-data.s3.ap-south-1.amazonaws.com/exports/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d.csv?...",
    "created_at": "2026-06-29T09:49:10Z",
    "completed_at": "2026-06-29T09:49:15Z"
  }
}

!!! success “Export Completed”

When the job status becomes **`completed`**, the `file_url` field contains a pre-signed Amazon S3 URL that can be used to download the exported CSV file.

- The URL is valid for **24 hours**.
- Download the file directly using any browser or HTTP client.
- No additional authentication is required while the pre-signed URL is valid.

Possible Job Statuses

Status	Description
`processing`	The export job is currently running.
`completed`	The export has finished successfully and the download URL is available.
`failed`	The export could not be completed. Check the error message and retry if necessary.

!!! tip

For large historical data requests, poll this endpoint periodically (for example, every **5–10 seconds**) until the job status changes to **`completed`**.