---
title: "Record CLI usage telemetry"
method: POST
path: "/api/v1/data/cli-usage"
---

# Record CLI usage telemetry

`POST /api/v1/data/cli-usage`

## Request

- Base URL: `https://moda.dev`
- URL: `https://moda.dev/api/v1/data/cli-usage`
- Auth: API key in header `x-api-key`

Records tenant-scoped, opt-in CLI invocation telemetry: one event, or an array of up to 50 events the CLI spooled locally (one invalid event rejects the batch). The CLI sends this asynchronously and does not depend on its success. Fields this API does not recognize are ignored rather than rejected, so a newer CLI never loses its event.

## Request body

- union
  - object
    - `invocation_id` string, required
    - `command` string, required
    - `status` 'success' | 'error', required
    - `error_type` 'validation_error' | 'auth_error' | 'access_error' | 'api_error' | 'api_not_found' | 'api_conflict' | 'api_client_error' | 'network_error' | 'unknown_error'
    - `exit_code` integer
    - `duration_ms` integer, required
    - `api_request_count` integer, required
    - `cli_version` string, required
    - `node_version` string, required
    - `platform` string, required
    - `arch` string, required
    - `flags_json` object, required
      - `names` string[], required
    - `subcommand` string
    - `output_mode` 'human' | 'json' | 'agent' | 'agent-stream'
    - `search_surface` 'none' | 'conversation' | 'world_state' | 'cluster' | 'message' | 'context'
    - `search_mode_requested` 'na' | 'keyword' | 'semantic' | 'hybrid'
    - `search_mode_effective` 'na' | 'keyword' | 'semantic' | 'hybrid'
    - `query_length` integer
    - `query_term_count` integer
    - `result_count` integer
    - `zero_result` 'na' | 'no' | 'yes'
    - `has_more` 'na' | 'no' | 'yes'
    - `used_msg_index` integer
    - `skill_version` string
    - `age_ms` integer: How long a spooled event waited on the client; it is dated that long before receipt.
  - object[]
    - `invocation_id` string, required
    - `command` string, required
    - `status` 'success' | 'error', required
    - `error_type` 'validation_error' | 'auth_error' | 'access_error' | 'api_error' | 'api_not_found' | 'api_conflict' | 'api_client_error' | 'network_error' | 'unknown_error'
    - `exit_code` integer
    - `duration_ms` integer, required
    - `api_request_count` integer, required
    - `cli_version` string, required
    - `node_version` string, required
    - `platform` string, required
    - `arch` string, required
    - `flags_json` object, required
      - `names` string[], required
    - `subcommand` string
    - `output_mode` 'human' | 'json' | 'agent' | 'agent-stream'
    - `search_surface` 'none' | 'conversation' | 'world_state' | 'cluster' | 'message' | 'context'
    - `search_mode_requested` 'na' | 'keyword' | 'semantic' | 'hybrid'
    - `search_mode_effective` 'na' | 'keyword' | 'semantic' | 'hybrid'
    - `query_length` integer
    - `query_term_count` integer
    - `result_count` integer
    - `zero_result` 'na' | 'no' | 'yes'
    - `has_more` 'na' | 'no' | 'yes'
    - `used_msg_index` integer
    - `skill_version` string
    - `age_ms` integer: How long a spooled event waited on the client; it is dated that long before receipt.

## Response `202`

Telemetry accepted.

- object
  - `accepted` true, required
  - `count` integer: Events stored, for a batch.

## Other responses

- `401`: The x-api-key header is missing, invalid, or revoked.
- `404`: The requested resource was not found.

---

[API](https://skmtc.dev/moda-dev/apis/moda-data-api.md) - [All operations](https://skmtc.dev/moda-dev/apis/moda-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/moda-dev/apis/moda-data-api/revisions/19a11ad88cf6?raw)