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

# Monitoring and usage

> Paint the home dashboard with GET /dashboard/summary and read run analytics with GET /usage

Two read-only aggregate endpoints back the operational screens of an app: `GET /dashboard/summary` is a one-call "what's happening right now" pulse, and `GET /usage` is a time-bucketed analytics series with a per-definition breakdown. Both compute live from your account's batches and schedules and return a single object — no pagination.

## Dashboard summary: `GET /dashboard/summary`

One call paints the home screen. The response composes four sections so the client makes no follow-up round trips.

```bash theme={null}
curl "$BASE_URL/dashboard/summary" \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

```json theme={null}
{
  "batches_by_status": {"completed": 128, "failed": 4, "running": 2},
  "recent_failures": [
    {
      "id": "batch_55667788",
      "definition_id": "def_a1b2c3d4",
      "source": "schedule",
      "failed_at": "2026-07-09T18:00:05Z"
    }
  ],
  "active_schedule_count": 6,
  "upcoming_fires": [
    {
      "schedule_id": "sched_1a2b",
      "definition_id": "def_a1b2c3d4",
      "next_fire_at": "2026-07-10T09:00:00Z"
    }
  ]
}
```

| Field                   | Type    | Description                                                                                                                                                                       |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batches_by_status`     | object  | Batch counts keyed by status over the **last 24 hours**.                                                                                                                          |
| `recent_failures`       | array   | The most recent failed batches, newest first — each row carries `id`, `definition_id`, `source`, and `failed_at`, denormalized so the failure feed renders without extra lookups. |
| `active_schedule_count` | integer | Number of currently-enabled schedules.                                                                                                                                            |
| `upcoming_fires`        | array   | The next few schedule fires, soonest first — `schedule_id`, `definition_id`, and the computed `next_fire_at` (UTC).                                                               |

## Usage analytics: `GET /usage`

`GET /usage` returns a time series of run activity plus a per-definition top-N volume table for the analytics screen.

### Query parameters

| Parameter     | Type     | Description                                 |
| ------------- | -------- | ------------------------------------------- |
| `from`        | datetime | Start of the range (inclusive).             |
| `to`          | datetime | End of the range (inclusive).               |
| `granularity` | enum     | Time-bucket size: `hour`, `day`, or `week`. |

<Note>
  The range is validated against the `granularity` so a single request can't ask for an unbounded number of buckets — for example, `hour` buckets are capped to a short span while `week` buckets allow a much longer one. A range that would produce too many buckets returns `422`. Bucket timestamps are UTC.
</Note>

```bash theme={null}
curl "$BASE_URL/usage?from=2026-07-01T00:00:00Z&to=2026-07-09T00:00:00Z&granularity=day" \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

```json theme={null}
{
  "series": [
    {"bucket": "2026-07-09T00:00:00Z", "total": 42, "succeeded": 40, "failed": 2}
  ],
  "top_definitions": [
    {"definition_id": "def_a1b2c3d4", "total": 128, "succeeded": 124}
  ]
}
```

| Field             | Type  | Description                                                                                                                                                 |
| ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `series`          | array | Per-bucket run counts over the range, oldest first. Each bucket carries `bucket` (start time, UTC), `total`, `succeeded`, and `failed`.                     |
| `top_definitions` | array | The busiest definitions in the range (\~top 20 by run count), each with `definition_id`, `total`, and `succeeded`. Success rates are derivable client-side. |

<Tip>
  The usage payload has no quota or plan block — it reports what ran, not entitlement limits. Compute success rate as `succeeded / total` per bucket or per definition on the client.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Batches and executions" icon="list-check" href="/concepts/batches-and-executions">
    Drill from a dashboard row into the account-wide runs feed.
  </Card>

  <Card title="Schedules" icon="clock" href="/concepts/schedules">
    Manage the schedules behind the upcoming-fires list.
  </Card>
</CardGroup>