> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironflow.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Ironflow API uptime history

> GET /v1/status/history returns an hourly uptime timeline for the Ironflow API: 24 buckets for 24h or 168 for 7d, each with the worst status seen in that hour.



## OpenAPI

````yaml GET /v1/status/history
openapi: 3.1.0
info:
  title: Ironflow API
  version: 1.0.0
  description: >
    Hyperliquid market data from Ironflow's own nodes: tick-level fills and

    trades, candles, funding rates, liquidations, mark prices, open interest,

    markets and wallet analytics over REST. One schema across native HL perps,

    HIP-3 builder markets, HIP-4 outcome contracts and HL spot.


    **Base URL:** `https://api.ironflow.sh`


    **Authentication:** Read endpoints work without a key (keyless access) or

    with a Bearer token in the `Authorization` header. Writes always need a key.

    ```

    Authorization: Bearer if_your_api_key

    ```

    Get a free key at https://ironflow.sh/key.


    **Access levels:**


    | Access | Requests per minute | History | Max range per request |

    |---|---|---|---|

    | No key | 10 per IP | 24 hours | 1 hour |

    | Free key | 60 | 30 days | 6 hours |

    | Explorer | 100 | 90 days | 24 hours |

    | Builder | 1,000 | 1 year | 7 days |

    | Enterprise | 10,000 | full | unlimited |


    Without a market filter, high-volume endpoints allow at most 4 hours per
    request.

    A header that is present but malformed returns 401; keyless access applies
    only

    when no `Authorization` header is sent.


    **Data availability:** fills and trades cover a rolling 12 months; other

    datasets start later (funding 2025-09-27, open interest and mark prices

    2026-04-29).


    **Timestamps:** All timestamps are Unix milliseconds (int64).


    **Pagination:** Paginated endpoints return a `cursor` in
    `pagination.next_cursor`.

    Pass it as the `cursor` query parameter to fetch the next page.

    When `pagination.has_more` is `false`, you have reached the last page.
  contact:
    name: Ironflow Support
    url: https://ironflow.sh
servers:
  - url: https://api.ironflow.sh
    description: Production
security:
  - bearerAuth: []
  - {}
tags:
  - name: Market Data
    description: Historical tick-level market data stored in ClickHouse.
  - name: Analytics
    description: Aggregated analytics endpoints (Builder tier and above).
  - name: Cohorts
    description: Predefined and custom address groups for filtering market data.
  - name: Info Proxy
    description: >-
      Cached passthrough to the Hyperliquid Info API. No record caps, higher
      rate limits.
  - name: Export
    description: Bulk data export as CSV or Parquet (Builder tier and above).
  - name: Query
    description: >-
      Read-only ClickHouse SQL over curated Hyperliquid tables (hl.*), limited
      by tier.
  - name: System
    description: Health checks and metadata endpoints.
  - name: TradingApp
    description: >-
      Trading app Phase A — wallet auth (SIWE), agent-key provisioning, and
      kill-switch.
paths:
  /v1/status/history:
    get:
      tags:
        - System
      summary: Uptime / freshness timeline
      description: |
        Returns a fixed-width uptime timeline of clock-hour buckets sourced from
        Prometheus. A `24h` request always returns exactly 24 buckets aligned
        to the top of each hour; `7d` returns 168. Each bucket reports the
        WORST status of every sample within that hour against the unified
        threshold band: `operational` when max data freshness across high-
        frequency tables (`fills`, `order_statuses`, `book_snapshots`,
        `mark_prices`, `open_interest`) stayed ≤ 60s for the entire hour,
        `degraded` past 60s, `down` past 5 minutes (or when Prometheus
        reported `NaN`).

        Buckets are aligned to clock hours rather than a sliding window so the
        timeline only changes shape at the top of each hour — a degraded tile
        cannot silently disappear between polls.

        `uptime_percent` is the share of buckets in `operational` state over
        the requested period.
      operationId: getStatusHistory
      parameters:
        - name: period
          in: query
          description: Lookback window. Defaults to `24h`.
          schema:
            type: string
            enum:
              - 24h
              - 7d
            default: 24h
      responses:
        '200':
          description: Uptime timeline for the requested period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusHistoryResponse'
              example:
                period: 24h
                uptime_percent: 99.86
                points:
                  - ts: 1745059200000
                    status: operational
                    fresh_sec: 1.4
                  - ts: 1745059800000
                    status: operational
                    fresh_sec: 1.8
      security: []
components:
  schemas:
    StatusHistoryResponse:
      type: object
      required:
        - points
        - uptime_percent
        - period
      properties:
        period:
          type: string
          enum:
            - 24h
            - 7d
        uptime_percent:
          type: number
          description: Share of buckets in `operational` state (0–100).
        points:
          type: array
          items:
            $ref: '#/components/schemas/UptimePoint'
    UptimePoint:
      type: object
      required:
        - ts
        - status
        - fresh_sec
      properties:
        ts:
          type: integer
          format: int64
          description: Bucket timestamp as Unix milliseconds.
        status:
          type: string
          enum:
            - operational
            - degraded
            - down
        fresh_sec:
          type: number
          description: >-
            Maximum data-freshness across high-frequency tables in this bucket
            (seconds).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Ironflow API key, format `if_xxxx`. Free keys at
        https://ironflow.sh/key. Optional on read endpoints.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.