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

# Custom Events

> Track custom events beyond what AgentCat captures out of the box.

AgentCat tracks each tool call of your MCP server by itself. Custom events let you go further and track actions specific to your application: feature usage, billing milestones, or anything else that matters to your product.

Custom events appear in the session replay timeline with a bolt icon, next to the tool calls. AgentCat uses the `resourceName` as the label. You can click any custom event to see its full details, including `parameters`, `response`, and `message`. If `isError` is `true`, the timeline styles the event as an error.

## Publishing events

After `track()`, `publishCustomEvent` sends an event for a tracked server. Its first argument is the tracked server instance:

```typescript TypeScript theme={null}
import * as agentcat from "agentcat"

await agentcat.publishCustomEvent(server, "proj_abc123xyz", {
  resourceName: "subscription_upgraded",
  parameters: {
    plan: "pro",
    source: "settings_page"
  }
})
```

```python Python theme={null}
import agentcat

agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "subscription_upgraded",
    "parameters": {
        "plan": "pro",
        "source": "settings_page"
    }
})
```

An event that you publish for a server has no session, unless its data gives a `sessionId` (`session_id` in Python). A tracked server can serve many tasks at once, so AgentCat cannot know by itself which session the event belongs to. The Rust SDK can also publish from inside a tool call, in the session of that call: see the [Rust reference](https://docs.agentcat.com/languages/rust/reference.md#the-call-context-in-a-tool).

## Using a session ID

If you know the `ses_` ID of a session instead of the server instance, you can pass it as a string. AgentCat uses the string as the session ID of the event, unchanged:

```typescript TypeScript theme={null}
await agentcat.publishCustomEvent("ses_2cOHEO0LYGADMzRvWTXXVbbgxgm", "proj_abc123xyz", {
  resourceName: "report_exported"
})
```

```python Python theme={null}
agentcat.publish_custom_event("ses_2cOHEO0LYGADMzRvWTXXVbbgxgm", "proj_abc123xyz", {
    "resource_name": "report_exported"
})
```

## publishCustomEvent reference

| Parameter | Type | Description |
| - | - | - |
| `serverOrSessionId` | Server \| string | A tracked MCP server instance, or a session ID string |
| `projectId` | string | Your AgentCat project ID (for example `proj_abc123xyz`) |
| `eventData` | object | The event data (optional, see below) |

## Event data

| Field | Type | Description |
| - | - | - |
| `sessionId` | string | The session of the event. It takes precedence over a session ID string as the first argument. |
| `resourceName` | string | A name for the event. It is the label in the dashboard timeline. Without it, the event shows as "Custom". |
| `parameters` | object | Any data to attach to the event. Visible in the event detail panel. |
| `response` | object | Response data to attach to the event. |
| `message` | string | A description of what happened. |
| `duration` | number | The duration of the event in milliseconds. |
| `isError` | boolean | `true` marks the event as an error. |
| `error` | object | Error details, usually a `message` and optionally a `type` or `code`. |
| `tags` | Record\<string, string> | String key-value pairs for filtering and grouping. AgentCat applies the [tag validation rules](https://docs.agentcat.com/sdk/event-tags-properties.md#tag-validation-rules). |
| `properties` | Record\<string, any> | Any JSON metadata. AgentCat does not validate it. |

All fields are optional. A call with only the server and the project ID records a minimal custom event.

You can also add metadata to every tool-call event that AgentCat captures: see [Event Tags & Properties](https://docs.agentcat.com/sdk/event-tags-properties.md).

## Custom events in your language

Each SDK has a function with these fields, named for the style of its language. The reference page of each language has more about it, from a short note to a full section with an example:

| Language | Function | Details |
| - | - | - |
| TypeScript | `agentcat.publishCustomEvent` | [Differences and known limits](https://docs.agentcat.com/languages/typescript/reference.md#differences-and-known-limits) |
| Python | `agentcat.publish_custom_event` | [Differences and known limits](https://docs.agentcat.com/languages/python/reference.md#differences-and-known-limits) |
| Go | `agentcat.PublishCustomEvent` | [Differences and known limits](https://docs.agentcat.com/languages/go/reference.md#differences-and-known-limits) |
| PHP | `AgentCat::publishCustomEvent` | [Custom events](https://docs.agentcat.com/languages/php/reference.md#custom-events) |
| C# | `AgentCatSdk.PublishCustomEventAsync`, or `IAgentCat` in a tool | [IAgentCat and custom events](https://docs.agentcat.com/languages/csharp/reference.md#iagentcat-and-custom-events) |
| Rust | `CallContext::publish_custom_event` in a tool, `AgentCat::publish_custom_event` elsewhere | [The call context in a tool](https://docs.agentcat.com/languages/rust/reference.md#the-call-context-in-a-tool) |
| Java | `AgentCat.publishCustomEvent` | [Differences and known limits](https://docs.agentcat.com/languages/java/reference.md#differences-and-known-limits) |
| Ruby | `AgentCat.publish_custom_event`, with the fields as keyword arguments (`resource_name:`, `session_id:`, ...) | [Differences and known limits](https://docs.agentcat.com/languages/ruby/reference.md#differences-and-known-limits) |

## Examples

### Tracking feature usage

You can record when users work with specific features, to understand adoption and usage patterns.

```typescript TypeScript theme={null}
await agentcat.publishCustomEvent(server, "proj_abc123xyz", {
  resourceName: "feature_used",
  parameters: {
    feature: "data_export",
    format: "json",
    recordCount: 250
  }
})
```

```python Python theme={null}
agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "feature_used",
    "parameters": {
        "feature": "data_export",
        "format": "json",
        "record_count": 250
    }
})
```

### Tracking errors

You can capture application errors that are not tied to a specific tool call.

```typescript TypeScript theme={null}
await agentcat.publishCustomEvent(server, "proj_abc123xyz", {
  resourceName: "rate_limit_hit",
  isError: true,
  error: { message: "Rate limit exceeded", code: "RATE_LIMIT" },
  parameters: {
    endpoint: "/api/search",
    limit: 100
  }
})
```

```python Python theme={null}
agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "rate_limit_hit",
    "is_error": True,
    "error": {"message": "Rate limit exceeded", "code": "RATE_LIMIT"},
    "parameters": {
        "endpoint": "/api/search",
        "limit": 100
    }
})
```

### Tracking user milestones

You can track when users reach key points in their journey, with a duration that measures how long it took.

```typescript TypeScript theme={null}
await agentcat.publishCustomEvent(server, "proj_abc123xyz", {
  resourceName: "onboarding_completed",
  message: "User finished all onboarding steps",
  parameters: {
    stepsCompleted: 5
  },
  duration: 200000
})
```

```python Python theme={null}
agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "onboarding_completed",
    "message": "User finished all onboarding steps",
    "parameters": {
        "steps_completed": 5
    },
    "duration": 200000
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.