---
title: "Ingest Plugin Telemetry"
method: POST
path: "/api/telemetry/plugin"
tags: ["Analytics"]
---

# Ingest Plugin Telemetry

`POST /api/telemetry/plugin`

## Request

- Base URL: `https://api.agentstack.tech` (the document declares no server; this is the origin it was published from)
- URL: `https://api.agentstack.tech/api/telemetry/plugin`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Ingest a batch of plugin usage events.

Authentication is optional — anonymous batches are accepted but tagged as
`anonymous` and rolled up separately so they cannot poison per-user stats.

## Headers

- `Idempotency-Key` string

## Request body

- PluginTelemetryBatch
  - `plugin` string, required: Plugin name, e.g. cursor-plugin
  - `version` string, required
  - `events` PluginTelemetryEvent[], required
    - `ts` integer, required: Unix millis when the event happened
    - `tool` string, nullable
    - `action` string, nullable
    - `success` boolean
    - `duration_ms` integer, nullable
    - `trace_id` string, nullable
    - `error` string, nullable
    - `plugin_version` string, nullable: cursor-plugin semver
    - `layer` string, nullable: hook | command | mcp
    - `gene_tag` string, nullable: Genetic tag for routing analytics

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/agentstack/apis/agentstack-core-api.md) · [All operations](https://skmtc.dev/agentstack/apis/agentstack-core-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentstack/apis/agentstack-core-api/revisions/79f4a4dd8813?raw)