> ## 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 Data

> Query historical uptime data for tracked services in DevHelm Status Data

DevHelm records uptime data for every service in the catalog. Query availability percentages over configurable time periods with different granularity levels to understand service reliability trends.

## Querying 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>

### Response format

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

## Periods and granularity

### Available periods

| Period | Description           |
| ------ | --------------------- |
| `24h`  | Last 24 hours         |
| `7d`   | Last 7 days           |
| `30d`  | Last 30 days          |
| `90d`  | Last 90 days          |
| `1y`   | Last year             |
| `2y`   | Last 2 years          |
| `all`  | All available history |

### Granularity options

| Granularity | Description              |
| ----------- | ------------------------ |
| `hourly`    | One data point per hour  |
| `daily`     | One data point per day   |
| `monthly`   | One data point per month |

### Period × granularity compatibility

Not all combinations are available:

| Period | `hourly` | `daily` | `monthly` |
| ------ | -------- | ------- | --------- |
| `24h`  | Yes      | Yes     | —         |
| `7d`   | Yes      | Yes     | —         |
| `30d`  | Yes      | Yes     | Yes       |
| `90d`  | Yes      | Yes     | Yes       |
| `1y`   | —        | Yes     | Yes       |
| `2y`   | —        | Yes     | Yes       |
| `all`  | —        | Yes     | Yes       |

Hourly granularity is not available for periods of 1 year or longer due to data volume.

## Uptime data sources

The `source` field indicates how uptime data is derived:

| Source             | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| `vendor_reported`  | Calculated from the vendor's reported component status                             |
| `incident_derived` | Calculated from incident records (used when vendor doesn't report granular status) |
| `poll_derived`     | Calculated from DevHelm's polling results                                          |

## Component uptime

Query uptime for a specific component of a service:

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

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

Find component IDs with `devhelm services components github`.

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

### Inline uptime summary

When listing components, each includes an `uptime` object:

| Field    | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| `day`    | double | Last 24 hours uptime percentage |
| `week`   | double | Last 7 days uptime percentage   |
| `month`  | double | Last 30 days uptime percentage  |
| `source` | string | Data source (see table above)   |

## 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 a period that exceeds your plan's limit returns only the available data within your tier. No error is returned — the response simply contains fewer buckets.

## Uptime response fields

| Field              | Type   | Description                                        |
| ------------------ | ------ | -------------------------------------------------- |
| `overallUptimePct` | double | Overall uptime percentage for the requested period |
| `period`           | string | Requested period (e.g., `30d`)                     |
| `granularity`      | string | Requested granularity (e.g., `daily`)              |
| `source`           | string | How uptime was calculated                          |
| `buckets`          | array  | Time-series data points                            |

### Bucket fields

| Field        | Type     | Description                       |
| ------------ | -------- | --------------------------------- |
| `timestamp`  | datetime | Start of the time bucket          |
| `uptimePct`  | double   | Uptime percentage for this bucket |
| `totalPolls` | integer  | Number of polls in this bucket    |

<Note>
  Service catalog browsing is public, but uptime data requires authentication and respects your plan's data access tier.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Services" icon="server" href="/status-data/services">
    Browse the catalog and view component-level detail.
  </Card>

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

  <Card title="Dependencies" icon="link" href="/status-data/dependencies">
    Track services and get alerted on status changes.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Full Status Data API endpoint reference.
  </Card>
</CardGroup>