events operations
MCP tools and operation permissions for events.
Generated from the shared operation catalog. Use the JSON catalog for complete input schemas. Required dependency checks can be stricter than the resource permission listed below.
events_capabilities_read
Read event storage readiness, the public ingestion URL, and dataset and retention limits. Supply a dataset ID to check its configured destination using your dataset read permission.
- HTTP:
GET /api/events/capabilities - SDK:
client.events.capabilities(input) - Access: workspace
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
id | Optional | string |
events_dataset_list
List readable event datasets and managed source IDs. Query these sources using the shared source/query/chart tools. Namespace and group are event fields; conditions filter data before aggregation.
- HTTP:
GET /api/events/datasets - SDK:
client.events.list(input) - Access: workspace; dataset / read
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
projectId | Optional | string |
events_dataset_create
Create an event dataset in a project with an optional destination, retention, masking policy and user-defined typed dimensions. Its managed source is registered automatically for queries, Views and dashboards. Retention is fixed at creation; ingestion credentials are created by the user in Events.
- HTTP:
POST /api/events/datasets - SDK:
client.events.create(input) - Access: workspace; dataset / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
name | Required | string |
projectId | Optional | See schema |
destinationId | Optional | See schema |
retentionDays | Optional | integer |
policy | Optional | object |
dimensions | Optional | array |
events_dataset_update
Update an event dataset name, destination, masking policy or typed dimensions using its current version. Read the latest dataset list before updating; retention cannot be changed.
- HTTP:
PATCH /api/events/datasets/:id - SDK:
client.events.update(input) - Access: workspace; dataset / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
version | Required | integer |
destinationId | Optional | See schema |
name | Optional | string |
policy | Optional | object |
dimensions | Optional | array |
events_dataset_delete
Delete an event dataset and its managed source and revoke all its ingestion keys. Stored events are removed through the destination cleanup process. Requires dataset administration permission.
- HTTP:
DELETE /api/events/datasets/:id - SDK:
client.events.remove(input) - Access: workspace; dataset / admin
- Effect annotation: May change state or run effects; destructive operation
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
events_credentials_list
List an event dataset ingestion key metadata: ID, name, token prefix, expiry and revocation state. Returns no bearer tokens or reusable secrets. Requires dataset administration permission.
- HTTP:
GET /api/events/datasets/:id/credentials - SDK:
client.events.listCredentials(input) - Access: workspace; dataset / admin
- Effect annotation: Read-only; destructive operation
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
events_credential_revoke
Revoke an existing event ingestion key by credential ID. Its applications can no longer ingest using that token. Requires dataset administration permission; does not create or return credentials.
- HTTP:
DELETE /api/events/datasets/:id/credentials/:credentialId - SDK:
client.events.revokeCredential(input) - Access: workspace; dataset / admin
- Effect annotation: May change state or run effects; destructive operation
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
credentialId | Required | string |
events_search
Read a dataset event stream with namespace, group, type, text search and typed dimension conditions. Omit both time bounds for the latest retained data or supply both from and to; use the returned next cursor when hasMore is true. Raw event details are retrieved separately by events_inspect.
- HTTP:
POST /api/events/datasets/:id/search - SDK:
client.events.search(input) - Access: workspace; dataset / read
- Effect annotation: Read-only
See the JSON schema for this input contract.
events_trace_read
Read up to 1000 retained spans for one exact trace ID in an authorized dataset, ordered by start time. Requires declared trace_id and span_id text dimensions and a duration_ms number dimension. Optional parent_span_id, span_name, service_name and span_status describe the tree. Uses event timestamp as span start; duration is milliseconds. Surface truncated and missing parents: returned spans do not prove a complete trace. Inspect original payloads separately with events_inspect. Does not search other datasets.
- HTTP:
POST /api/events/datasets/:id/trace - SDK:
client.events.trace(input) - Access: workspace; dataset / read
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
traceId | Required | string |
events_inspect
Inspect one stored event, including its full data payload, using the event ID, namespace and group from events_search. Dataset read permission and masking policy apply.
- HTTP:
POST /api/events/datasets/:id/inspect - SDK:
client.events.inspect(input) - Access: workspace; dataset / read
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
eventId | Required | string |
namespace | Required | string |
group | Required | string |
events_ingest
Append a bounded batch of events to a dataset using your existing dataset ingestion permission. Each event has an ID, timestamp, namespace, group, type, optional declared dimensions and data. The destination validates and masks the batch before accepting it; this does not create an ingestion credential.
- HTTP:
POST /api/events/datasets/:id/ingest - SDK:
client.events.ingest(input) - Access: workspace; dataset / ingest
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
batch | Required | object |
events_groups_read
Count dataset events grouped by up to four namespace, group, type, ID or declared dimension fields. Apply conditions before aggregation. Omit both time bounds for all retained data or supply both from and to. Surface total and truncated when presenting results; use the managed source query tools for chart and dashboard analytics.
- HTTP:
POST /api/events/datasets/:id/groups - SDK:
client.events.groups(input) - Access: workspace; dataset / read
- Effect annotation: Read-only
See the JSON schema for this input contract.