> For the complete documentation index, see [llms.txt](https://statalpha.gitbook.io/statalpha-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://statalpha.gitbook.io/statalpha-docs/stats/intraday.md).

# Intraday

The **Intraday Statistics** module analyzes how returns, volume, and direction behave within fixed intraday time slots.\
It helps identify statistically favorable **windows for entries or exits** based on historical intraday performance.

***

## Concept

* Each trading day is divided into fixed-length slots (e.g. 15 minutes).
* For every slot, the system calculates:
  * **Average & median return (%)**
  * **Average volume**
  * **Positive rate** (how often the slot closes green)
  * **Absolute return (%)** — a proxy for volatility
* The analysis highlights **which time periods tend to perform best or worst** for a given symbol.

***

## Parameters

| Parameter                 | Type   | Description                                                             |
| ------------------------- | ------ | ----------------------------------------------------------------------- |
| `symbol`                  | string | Asset symbol (e.g. `AAPL`, `BTCUSD`)                                    |
| `start_date` / `end_date` | string | Optional date range (`YYYY-MM-DD`)                                      |
| `time_window`             | string | Predefined relative range (e.g. `1M`, `3M`, `6M`, `12M`, `24M`, `5Y`)   |
| `resolution_minutes`      | int    | Slot duration in minutes (default `15`, min `1`, max `240`)             |
| `start_time` / `end_time` | string | UTC session range (default `13:30`–`20:00`)                             |
| `include_extended_hours`  | bool   | Include pre-/post-market data                                           |
| `sort_by`                 | string | Sorting field for summary/top (`avg_return_pct` or `median_return_pct`) |
| `direction`               | string | For `/top`: `'top'` (best slots) or `'bottom'` (worst slots)            |
| `limit`                   | int    | Number of slots returned by `/top` (default `5`, max `100`)             |

***

## Endpoints

| Endpoint                      | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| `GET /stats/intraday/slots`   | Returns average metrics per intraday time slot (e.g. every 15 minutes) |
| `GET /stats/intraday/summary` | Returns the best and worst slot by average or median return            |
| `GET /stats/intraday/top`     | Returns ranked list of top or bottom slots                             |
| `GET /stats/intraday/doc`     | Returns documentation of all intraday fields                           |

***

## Example Requests

### 1. Get all intraday slot statistics

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/intraday/slots?symbol=AAPL&time_window=6M&resolution_minutes=15"
```

### 2. Find best and worst slot

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/intraday/summary?symbol=AAPL&sort_by=median_return_pct"
```

### 3. Get top 5 intraday slots

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/intraday/top?symbol=AAPL&direction=top&limit=5"
```

***

## Example Response (summary excerpt)

```json
{
  "symbol": "AAPL",
  "sort_by": "median_return_pct",
  "best_slot": {
    "slot": "15:15:00",
    "median_return_pct": 0.043,
    "avg_volume": 1230000
  },
  "worst_slot": {
    "slot": "19:00:00",
    "median_return_pct": -0.026,
    "avg_volume": 1010000
  },
  "time_window": "12M"
}
```

***

## Interpretation

| Metric                                     | Meaning                                                    |
| ------------------------------------------ | ---------------------------------------------------------- |
| **avg\_return\_pct / median\_return\_pct** | Average or median return for each slot                     |
| **absolute\_return\_pct**                  | Average magnitude of price movement (volatility indicator) |
| **positive\_rate\_pct**                    | Percentage of sessions where the slot closed positive      |
| **avg\_volume**                            | Mean traded volume during this slot                        |
| **count**                                  | Number of data points used for that slot                   |
| **best\_slot / worst\_slot**               | Slots with the highest and lowest performance metrics      |

***

## Notes

* All intraday analyses use **aggregated bar data** (minute to hourly resolutions).
* Session times and slot lengths can be customized depending on your subscription plan.
* Cached responses ensure consistent performance for repeated queries.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://statalpha.gitbook.io/statalpha-docs/stats/intraday.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.