# Human, agent and unknown interaction minutes and sessions per day

`GET /api/v1/activity.json` · operationId `getActivity`

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open **Home and Your agent report** in the dashboard.

For BI tools: interaction minutes per class (human, agent, unknown, mixed) and daily session totals by last-observed verdict, in UTC-day or ISO-week buckets that partition [since, until). Compute a share as one class divided by total; it is a share of minutes or sessions, not a probability. Unknown is never counted as human.

## Authentication

Send `Authorization: Bearer YOUR_SERVER_KEY` (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

## Parameters

- `from` (query, string, optional): Period start: Unix epoch ms or ISO 8601 date. Defaults to the last 7 days: 7 whole UTC days ending today; clamped to the Site usage retention (90 days by default, up to 400 in Settings › Data).
- `to` (query, string, optional): Period end (exclusive); defaults to now.
- `series` (query, "day" | "week", optional)

## Responses

- **200**: Activity series · body `Activity`
- **400**: bad_request: the request is invalid; message says what to fix and field names the request field · body `Error`
- **401**: unauthorized (missing or invalid server key, missing Bearer scheme) · body `Error`
- **403**: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body `Error`
- **404**: not_found: nothing with this ID on this Site (or it is past retention), or an unknown path · body `Error`
- **429**: rate_limited: wait for Retry-After · body `Error` · headers `Retry-After`
- **500**: internal_error: fail the protected action; do not retry automatically · body `Error`
- **503**: service_unavailable: temporarily unavailable; only verify retries · body `Error`

### Success body fields

- `siteId` (string, required)
- `since` (number, required): Unix epoch milliseconds.
- `until` (number, required): Unix epoch milliseconds.
- `periodBounds` ("[since, until)", required)
- `window` (string, required): The period in words: last 7 days: 7 whole UTC days ending with today, or from and to as given (UTC).
- `bucket` ("UTC day" | "ISO week (Monday 00:00 UTC)", required)
- `clampedToRetention` (boolean, required)
- `totals` (object, required)
- `totals.minutes` (object, required)
- `totals.minutes.human` (integer, required)
- `totals.minutes.agent` (integer, required)
- `totals.minutes.unknown` (integer, required)
- `totals.minutes.mixed` (integer, required)
- `totals.minutes.total` (integer, required)
- `totals.minutes.percent` (object, required): Shares of minutes rounded to one decimal (largest remainder), not probabilities.
- `series` (object[], required)
- `series[].start` (number, required): Unix epoch milliseconds.
- `series[].end` (number, required): Unix epoch milliseconds.
- `series[].minutes` (object, required)
- `series[].minutes.human` (integer, required)
- `series[].minutes.agent` (integer, required)
- `series[].minutes.unknown` (integer, required)
- `series[].minutes.mixed` (integer, required)
- `series[].minutes.total` (integer, required)
- `series[].sessions` (object | null, required): Whole-UTC-day session totals by last-observed verdict that this bucket overlaps; null where no daily total exists.
- `series[].sessions.human` (integer, optional)
- `series[].sessions.agent` (integer, optional)
- `series[].sessions.unknown` (integer, optional)
- `series[].sessions.total` (integer, optional)
- `sessionRollupStart` (number | null, required)
- `coverage` (string, required)

Failures are not verdicts. Error bodies follow the `Error` schema: `code` is one of `bad_request`, `unauthorized`, `session_reinit_required`, `forbidden`, `not_found`, `conflict`, `identity_required`, `payload_too_large`, `rate_limited`, `internal_error`, `service_unavailable`, `request_failed`, `approval_invalid`, `approval_used`, `approval_expired`, `approval_mismatch`, `step_up_not_held`, `step_up_mismatch`, `step_up_settled`, `step_up_expired`, `step_up_superseded`, `agent_tokens_disabled`, `tool_not_approved`, `tool_not_read_only`. [Errors and retries](/docs/errors) explains each code and what to do.

## Example

```sh tab=curl
curl -sS -X GET 'https://app.trytelltale.dev/api/v1/activity.json' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY"
```

```js tab=fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/activity.json", {
  method: "GET",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY
  },
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();
```

Machine-readable contract: [openapi.json](https://app.trytelltale.dev/openapi.json). Request builder: the [API explorer](/docs/api-explorer) shows every operation as curl; it sends requests only on a local dashboard.