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

# productTelemetry

> Privacy-bounded first-party product funnel events and organization-level aggregate evidence.

Privacy-bounded first-party product funnel events and organization-level aggregate evidence.

## productTelemetry.track

Accept a bounded batch of public allowlisted events with a closed low-cardinality property schema per event. Raw network addresses, secrets, personal data, nested objects, arbitrary property names, and authoritative lifecycle claims are rejected.

```text theme={null}
POST /v1/telemetry/events
```

* **Auth:** None — public endpoint.
* **Risk:** `write` · sensitive (elevated blast radius)

### Request body

| Field                         | Type                                                                                                | Required | Description                                                                                                                    |
| ----------------------------- | --------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `events`                      | object or object or object or object or object or object or object or object or object or object\[] | Yes      | —                                                                                                                              |
| `events[].name`               | string                                                                                              | Yes      | One of: `cli_installed`.                                                                                                       |
| `events[].at`                 | string                                                                                              | Yes      | When the event occurred. Events outside the accepted clock window are rejected. Format: `date-time`.                           |
| `events[].anonymousId`        | string                                                                                              | No       | Optional random installation UUID. The service stores only a one-way digest. Format: `uuid`.                                   |
| `events[].organizationId`     | string                                                                                              | No       | Optional post-auth correlation claim. Public claims are digested and never trusted for organization reporting. Format: `uuid`. |
| `events[].properties`         | object                                                                                              | Yes      | —                                                                                                                              |
| `events[].properties.channel` | string                                                                                              | Yes      | One of: `shell`.                                                                                                               |
| `events[].properties.os`      | string                                                                                              | Yes      | One of: `Darwin`, `Linux`.                                                                                                     |
| `events[].properties.arch`    | string                                                                                              | Yes      | One of: `arm64`, `aarch64`, `x86_64`.                                                                                          |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/telemetry/events" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "name": "cli_installed",
      "at": "2026-06-01T12:00:00Z",
      "properties": {
        "channel": "shell",
        "os": "Darwin",
        "arch": "arm64"
      }
    }
  ]
}'
```

### Responses

| Status | Description                                                   |
| ------ | ------------------------------------------------------------- |
| `202`  | The bounded event batch was accepted for first-party storage. |
| `413`  | The encoded request exceeds 65,536 bytes.                     |
| `422`  | The event batch is malformed or outside the privacy bounds.   |
| `429`  | The global or trusted-edge network budget is exhausted.       |
| `503`  | The keyed privacy boundary is not configured.                 |

### Response body (202)

| Field      | Type    | Description |
| ---------- | ------- | ----------- |
| `accepted` | integer | —           |

## productTelemetry.getFunnel

Return aggregate, server-verified onboarding funnel evidence for this organization. Each result names its deduplication grain; anonymous and untrusted public correlation data is never returned.

```text theme={null}
GET /v1/orgs/{orgId}/telemetry/funnel
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Risk:** `read`

### Query parameters

| Name    | Type   | Required | Description          |
| ------- | ------ | -------- | -------------------- |
| `since` | string | No       | Format: `date-time`. |
| `until` | string | No       | Format: `date-time`. |

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/telemetry/funnel?since=2026-06-01T12%3A00%3A00Z" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                                                                |
| ------ | ------------------------------------------------------------------------------------------ |
| `200`  | Aggregate authoritative event counts, explicit grains, and first/last evidence timestamps. |
| `422`  | The requested window is invalid or exceeds 90 days.                                        |

### Response body (200)

| Field             | Type           | Description                                                           |
| ----------------- | -------------- | --------------------------------------------------------------------- |
| `since`           | string         | Format: `date-time`.                                                  |
| `until`           | string         | Format: `date-time`.                                                  |
| `steps`           | object\[]      | —                                                                     |
| `steps[].name`    | string         | One of: `billing_activated`, `first_deploy_ready`, `agent_connected`. |
| `steps[].grain`   | string         | One of: `organization`, `agent_grant`.                                |
| `steps[].count`   | integer        | —                                                                     |
| `steps[].firstAt` | string or null | Format: `date-time`.                                                  |
| `steps[].lastAt`  | string or null | Format: `date-time`.                                                  |