> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Create, retrieve, update, delete, and test OpenTelemetry log destinations through the REST API.

# Telemetry

The Telemetry API manages the OpenTelemetry destinations shown under
**Telemetry** (`/app/telemetry`) in the dashboard. Use it to export security
events as OTLP logs to Datadog, Grafana Cloud, or your own collector without
using the dashboard.

All requests require an organization API key sent as a bearer token in the
`Authorization` header, as described in the [REST API](https://www.superagent.sh/docs/api).
Destinations are scoped to the API key's organization. Only OTLP destinations
are visible through this API; signed `webhook` targets remain available
through the dashboard and [Webhooks](https://www.superagent.sh/docs/webhooks).

## Endpoints

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/telemetry` | List OpenTelemetry destinations, newest first |
| `POST` | `/telemetry` | Create a destination |
| `GET` | `/telemetry/{endpoint_id}` | Retrieve one destination |
| `PATCH` | `/telemetry/{endpoint_id}` | Update a destination |
| `DELETE` | `/telemetry/{endpoint_id}` | Delete a destination |
| `POST` | `/telemetry/{endpoint_id}/test` | Send a synthetic OTLP log event |

```bash
export SUPERAGENT_API_KEY="sk_live_..."
export SUPERAGENT_API_URL="https://superagent.sh/api/v1"
```

## Create a destination

`POST /api/v1/telemetry` creates an opt-in export destination. Export is
paused when `enabled` is `false`.

```bash
curl -X POST "$SUPERAGENT_API_URL/telemetry" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Datadog production",
    "url":"https://http-intake.logs.datadoghq.com/api/v2/otlp/v1/logs",
    "protocol":"otlp_http_protobuf",
    "headers":{"dd-api-key":"replace-with-a-datadog-api-key"},
    "event_types":["finding.created","finding.triage_completed","report.finished"],
    "source_types":["repository","application","agent"]
  }'
```

### Request fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Destination name, 1–120 characters. |
| `url` | string | Yes | Full public HTTPS OTLP logs endpoint, including the path such as `/v1/logs`. Superagent uses this exact URL without appending a path. Private hosts, `localhost`, non-HTTPS URLs, and URLs with credentials, query strings, or fragments are rejected. |
| `protocol` | string | No | `otlp_http_protobuf` (default) or `otlp_http_json`. Datadog direct OTLP logs intake requires `otlp_http_protobuf`. |
| `enabled` | boolean | No | Enable event export. Defaults to `true`. |
| `event_types` | string[] | No | Subscribed [webhook events](https://www.superagent.sh/docs/webhooks#events). Defaults to all events. Must be non-empty when provided. |
| `source_types` | string[] | No | Subscribed source groups: `repository`, `application`, `agent`, `infrastructure`. Defaults to all sources. Must be non-empty when provided. |
| `source_filters` | object | No | Restrict delivery to specific sources: `{ "repository": ["1095278383"], "application": [], "agent": [] }`. IDs must belong to the organization. Empty arrays receive all sources in subscribed groups. |
| `headers` | object or null | No | Authentication headers stored encrypted, for example `{"dd-api-key":"..."}`. At most 20 headers; reserved webhook headers cannot be overridden. Header values are never returned. Omit to create a destination without headers. |

`201 Created` returns the destination under `data` with `object:
"telemetry_endpoint"`. The response includes `has_headers` instead of header
values.

```json
{
  "data": {
    "id": "3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b",
    "object": "telemetry_endpoint",
    "name": "Datadog production",
    "url": "https://http-intake.logs.datadoghq.com/api/v2/otlp/v1/logs",
    "protocol": "otlp_http_protobuf",
    "enabled": true,
    "event_types": ["finding.created", "finding.triage_completed", "report.finished"],
    "source_types": ["repository", "application", "agent"],
    "source_filters": { "repository": [], "application": [], "agent": [] },
    "has_headers": true,
    "created_at": "2026-10-02T07:00:00.000Z",
    "updated_at": "2026-10-02T07:00:00.000Z"
  }
}
```

## List and retrieve destinations

`GET /api/v1/telemetry` returns all OTLP destinations, newest first, under
`data` as an array. `GET /api/v1/telemetry/{endpoint_id}` returns one
destination. Both use the same object shape as the create response. Header
values are never returned; use `has_headers` to check whether credentials are
configured.

```bash
curl "$SUPERAGENT_API_URL/telemetry" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

curl "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"
```

Destinations with the signed `webhook` transport are not listed and return
`404 not_found` when requested by ID through this API.

## Update a destination

`PATCH /api/v1/telemetry/{endpoint_id}` updates only the fields provided.
Omitted fields preserve their saved values, including saved authentication
headers.

```bash
curl -X PATCH "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "protocol": "otlp_http_json"
  }'
```

To replace authentication headers, send a new `headers` object. To clear saved
headers, send `"headers": null` or `"headers": {}`. Omitting `headers` keeps
the saved credentials. The protocol can switch between `otlp_http_protobuf`
and `otlp_http_json`; switching between OTLP and signed webhooks is rejected —
create a new destination instead.

A request with no supported fields returns `400 invalid_request`.

## Delete a destination

`DELETE /api/v1/telemetry/{endpoint_id}` permanently deletes the destination
and stops exporting events to it.

```bash
curl -X DELETE "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"
```

The response is `200 OK` with `{ "data": { "deleted": true } }`. This cannot
be undone.

## Test a destination

`POST /api/v1/telemetry/{endpoint_id}/test` sends a synthetic OTLP log event
directly to the collector and returns whether it was accepted. It does not go
through the queued event outbox.

```bash
curl -X POST "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b/test" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"
```

```json
{
  "data": {
    "ok": true,
    "status": 200,
    "event_type": "report.finished"
  }
}
```

`ok: false` means the collector rejected the event or returned an invalid OTLP
export response. Check the endpoint URL, protocol, and credentials, then retry.
To verify the queued event path instead, trigger a subscribed action — such as
starting a report — and look for its event in your destination. See
[Telemetry](https://www.superagent.sh/docs/telemetry) for Datadog setup and delivery details.

## Events and delivery

Telemetry exports the same [event catalog](https://www.superagent.sh/docs/webhooks#events) and uses the
same [source matching rules](https://www.superagent.sh/docs/webhooks#filter-by-source) as webhooks.
Each event becomes an OTLP log record with `service.name: superagent`; the
body contains the webhook event envelope. The export shares the event outbox,
source matching, and asynchronous retry behavior used by webhooks. Header
values are encrypted at rest and are never shown after saving.

## MCP tools

The same operations are available through the [Superagent MCP server](https://www.superagent.sh/docs/mcp):

| REST operation | MCP tool | Arguments |
| --- | --- | --- |
| List destinations | `list_telemetry_endpoints` | None |
| Retrieve a destination | `get_telemetry_endpoint` | `endpoint_id` |
| Create a destination | `create_telemetry_endpoint` | `name`, `url`, optional `protocol`, `enabled`, `event_types`, `source_types`, `source_filters`, `headers` |
| Update a destination | `update_telemetry_endpoint` | `endpoint_id` plus the fields to change; `headers: null` clears saved headers |
| Delete a destination | `delete_telemetry_endpoint` | `endpoint_id` |
| Send a test event | `test_telemetry_endpoint` | `endpoint_id` |

MCP responses match the REST payloads for list, retrieve, create, update, and test, including `has_headers` instead of
header values. The delete tool also returns `endpoint_id` alongside `deleted`.

## Errors

| HTTP status | Code | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | Invalid URL, protocol, event type, source type, source filter, header, or state transition |
| `401` | `unauthorized` | Missing or invalid organization API key |
| `404` | `not_found` | Destination is missing, belongs to another organization, or uses the signed webhook transport |
| `500` | `internal_error` | Unexpected server failure |

## Next steps

- [Export events with Telemetry](https://www.superagent.sh/docs/telemetry)
- [Subscribe to events with Webhooks](https://www.superagent.sh/docs/webhooks)
- [Use Superagent MCP](https://www.superagent.sh/docs/mcp)

---
Source: https://www.superagent.sh/docs/api/telemetry
Index: https://www.superagent.sh/llms.txt