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

# Activity & Observability

> Customer-visible activity events and structured telemetry ingestion

Every meaningful thing that happens to your resources — a sandbox starting, an agent run, a tool call, a workspace write, a device change — is recorded as a customer-visible activity event. Think of it as your product-facing audit trail, separate from the canonical thread transcripts and from the operational logs and metrics Runtools runs on internally.

## Activity Model

Each event has a resource, an actor, a status, a severity, timestamps, and optional attributes.

| Field          | Meaning                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `resourceType` | `sandbox`, `agent`, `workspace`, `thread`, `tool`, `installable_agent_install`, `runmesh_device`, or `code_execution` |
| `resourceId`   | Resource identifier                                                                                                   |
| `eventType`    | Machine-readable event name such as `agent.run.started`                                                               |
| `severity`     | `debug`, `info`, `notice`, `warning`, `error`, or `critical`                                                          |
| `status`       | Event-specific state such as `started`, `completed`, `failed`, or `added`                                             |
| `actorUserId`  | User who caused the event when known                                                                                  |

Common event families include:

* `sandbox.*` for create, wake, pause, resume, delete, terminal, SSH, VNC, and dev URL activity.
* `agent.*`, `thread.*`, and `tool.*` for agent runs, messages, tool calls, installs, executions, and publishes.
* `workspace.*` for workspace CRUD, file changes, quota events, and storage usage.
* `credential.*`, `billing.*`, `code_exec.*`, `runmesh.*`, and `installable_agent.*` for the matching platform primitives.

## Access Rules

Members see their own activity by default. Resource-scoped requests can return events for a resource the caller is allowed to access. Organization admins can filter across actors inside the organization.

Activity attributes are sanitized before storage. They do not expose raw prompts, chat messages, command output, provider names, API keys, bearer tokens, signed URLs, hostnames, backend paths, or secrets. File paths in activity attributes are relative to the visible workspace/resource.

## Common Filters

```bash cURL theme={null}
curl "https://api.runtools.ai/v1/activity?resource_type=sandbox&resource_id=sandbox-abc123&limit=50" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

```bash cURL theme={null}
curl "https://api.runtools.ai/v1/threads/thr_abc123/activity" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Use `since` and `until` for time windows, and `cursor` for pagination. `limit` defaults to `50` and is capped at `200`.

Supported filters include:

* `resource_type`, `resource_id`, `event_type`, `severity`, and `status`
* `thread_id`, `agent_run_id`, `sandbox_id`, `workspace_id`, `tool_slug`, `installable_agent_install_id`, `code_execution_id`, and `runmesh_node_id`
* `actor_user_id` for organization admins

## Telemetry Ingestion

Applications and local runtimes can submit structured telemetry through:

```bash cURL theme={null}
curl -X POST "https://api.runtools.ai/v1/observability/ingest" \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Runtools-Service: my-client" \
  -H "X-Runtools-Environment: production" \
  -d '{
    "records": [
      {
        "type": "event",
        "eventName": "client.sync.completed",
        "severity": "info",
        "summary": "Client sync finished"
      }
    ]
  }'
```

The ingest endpoint accepts `event`, `span`, and `metric` records. It returns `202 Accepted` with counts for accepted, dropped, and invalid records. Batches are capped at 500 records.

`log` and `audit` records are not accepted by the public ingest endpoint.

## What Activity Is Not

Activity events are not the canonical thread transcript. Thread content lives in the thread event APIs. Transient token, reasoning, and tool-output deltas are live-only and are not activity rows.

Activity is also not a provider-level trace. Customer-facing surfaces show model and product behavior without exposing the underlying routing path.

<Card title="Activity API" icon="clock-rotate-left" href="/api-reference/activity">
  Query the org activity feed and resource-scoped activity endpoints.
</Card>