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

# Uptime Reporting

> Query and present historical uptime data from DevHelm Status Data

By the end of this guide, you'll know how to query uptime data for third-party services, select the right periods and granularity, and build uptime reports.

<Accordion title="Prerequisites">
  * DevHelm CLI installed or an API token
  * At least one service dependency — see [Tracking dependencies](/guides/tracking-dependencies)
</Accordion>

For conceptual background, see [Uptime data](/status-data/uptime).

## Query service uptime

<CodeGroup>
  ```bash CLI theme={null}
  devhelm services uptime github --period 30d --granularity daily
  ```

  ```bash API theme={null}
  curl "https://api.devhelm.io/api/v1/services/github/uptime?period=30d&granularity=daily" \
    -H "Authorization: Bearer $DEVHELM_API_TOKEN"
  ```
</CodeGroup>

The response includes the overall uptime percentage and time-bucketed data:

```json theme={null}
{
  "overallUptimePct": 99.95,
  "period": "30d",
  "granularity": "daily",
  "source": "vendor_reported",
  "buckets": [
    { "timestamp": "2026-03-14T00:00:00Z", "uptimePct": 100.0, "totalPolls": 288 },
    { "timestamp": "2026-03-15T00:00:00Z", "uptimePct": 99.8, "totalPolls": 288 }
  ]
}
```

## Choose the right period and granularity

| Use case                  | Period | Granularity          |
| ------------------------- | ------ | -------------------- |
| Ops dashboard (real-time) | `24h`  | `hourly`             |
| Weekly team review        | `7d`   | `daily`              |
| Monthly SLA report        | `30d`  | `daily`              |
| Quarterly business review | `90d`  | `daily` or `monthly` |
| Annual vendor evaluation  | `1y`   | `monthly`            |

<Note>
  Hourly granularity is not available for periods of 1 year or longer.
</Note>

## Component-level uptime

Drill into specific components for more granular reporting:

```bash theme={null}
devhelm services components github

curl "https://api.devhelm.io/api/v1/services/github/components/<component-id>/uptime?period=30d" \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"
```

Components also include inline uptime summaries (24h, 7d, 30d) in the component listing, so you can get a quick overview without separate queries.

## Build a dependency uptime report

Query uptime for all your dependencies to build a report:

<Steps>
  <Step title="List your dependencies">
    ```bash theme={null}
    devhelm dependencies list
    ```
  </Step>

  <Step title="Query uptime for each">
    ```bash theme={null}
    for slug in github stripe aws vercel; do
      echo "=== $slug ==="
      curl -s "https://api.devhelm.io/api/v1/services/$slug/uptime?period=30d&granularity=daily" \
        -H "Authorization: Bearer $DEVHELM_API_TOKEN" | jq '.overallUptimePct'
    done
    ```
  </Step>

  <Step title="Correlate with incidents">
    For services with low uptime, check their incident history:

    ```bash theme={null}
    curl "https://api.devhelm.io/api/v1/services/github/incidents?status=resolved" \
      -H "Authorization: Bearer $DEVHELM_API_TOKEN"
    ```
  </Step>
</Steps>

## Data access tiers

Historical data depth depends on your plan:

| Plan      | Max aggregated data | Max incident history |
| --------- | ------------------- | -------------------- |
| Free      | 90 days             | 90 days              |
| Pro       | 365 days            | Unlimited            |
| Team      | 730 days            | Unlimited            |
| Business+ | Unlimited           | Unlimited            |

Requesting data beyond your plan's limit returns only available data — no error, just fewer buckets.

## Next steps

<CardGroup cols={2}>
  <Card title="Uptime data reference" icon="chart-line" href="/status-data/uptime">
    Full period/granularity matrix and response format.
  </Card>

  <Card title="Service incidents" icon="circle-exclamation" href="/status-data/incidents">
    View outages that caused uptime dips.
  </Card>

  <Card title="Status Data guide" icon="server" href="/guides/status-data">
    Full Status Data system overview.
  </Card>
</CardGroup>