> ## 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 automatically tracks MCP protocol events like tool calls and session initialization. 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, alongside automatic MCP events. The `resourceName` is used as the label. Click on any custom event to see its full details, including `parameters`, `response`, and `message`.

If `isError` is set to `true`, the event is styled as an error in the timeline.

## Publishing Events

After calling `agentcat.track()`, use `publishCustomEvent` to send events tied to the current session. Pass the tracked server instance as the first argument.

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

  await agentcat.publishCustomEvent(mcpServer, "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"
      }
  })
  ```

  ```go Go theme={null}
  import mcpcat "github.com/mcpcat/mcpcat-go-sdk/officialsdk"
  // For mark3labs/mcp-go: import mcpcat "github.com/mcpcat/mcpcat-go-sdk/mcpgo"

  mcpcat.PublishCustomEvent(s, "proj_abc123xyz", mcpcat.EventData{
      ResourceName: "subscription_upgraded",
      Parameters: map[string]any{
          "plan":   "pro",
          "source": "settings_page",
      },
  })
  ```
</CodeGroup>

## Using a Session ID

If you have a session ID instead of the server instance, you can pass it directly as a string. AgentCat will derive a stable session from it.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await agentcat.publishCustomEvent("user-session-12345", "proj_abc123xyz", {
    resourceName: "report_exported"
  })
  ```

  ```python Python theme={null}
  agentcat.publish_custom_event("user-session-12345", "proj_abc123xyz", {
      "resource_name": "report_exported"
  })
  ```

  ```go Go theme={null}
  mcpcat.PublishCustomEvent("user-session-12345", "proj_abc123xyz", mcpcat.EventData{
      ResourceName: "report_exported",
  })
  ```
</CodeGroup>

## publishCustomEvent Reference

| Parameter           | Type             | Required | Description                                           |
| ------------------- | ---------------- | -------- | ----------------------------------------------------- |
| `serverOrSessionId` | Server \| string | Yes      | A tracked MCP server instance, or a session ID string |
| `projectId`         | string           | Yes      | Your AgentCat project ID (e.g. `proj_abc123xyz`)      |
| `eventData`         | object           | No       | The event payload (see below)                         |

## Event Data

| Field          | Type                    | Description                                                                                                                                    |
| -------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `resourceName` | string                  | A name for the event. Shows as the label in the dashboard timeline. If omitted, the event shows as "Custom".                                   |
| `parameters`   | object                  | Arbitrary data to attach to the event. Visible in the event detail panel.                                                                      |
| `response`     | object                  | Response data to attach to the event.                                                                                                          |
| `message`      | string                  | A human-readable description of what happened.                                                                                                 |
| `duration`     | number                  | Duration of the event in milliseconds.                                                                                                         |
| `isError`      | boolean                 | Set to `true` to mark this event as an error.                                                                                                  |
| `error`        | object                  | Error details. Typically includes `message` and optionally `type` or `code`.                                                                   |
| `tags`         | Record\<string, string> | Indexed string key-value pairs for filtering and grouping. Subject to [tag validation rules](/sdk/event-tags-properties#tag-validation-rules). |
| `properties`   | Record\<string, any>    | Arbitrary JSON metadata. No client-side validation constraints.                                                                                |

All fields in `eventData` are optional. You can call `publishCustomEvent` with just the server and project ID to record a minimal custom event.

You can also enrich every auto-captured event with metadata — see [Event Tags & Properties](/sdk/event-tags-properties).

## Examples

### Tracking Feature Usage

Record when users interact with specific features to understand adoption and usage patterns.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await agentcat.publishCustomEvent(mcpServer, "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
      }
  })
  ```

  ```go Go theme={null}
  mcpcat.PublishCustomEvent(s, "proj_abc123xyz", mcpcat.EventData{
      ResourceName: "feature_used",
      Parameters: map[string]any{
          "feature":     "data_export",
          "format":      "json",
          "recordCount": 250,
      },
  })
  ```
</CodeGroup>

### Tracking Errors

Capture application-level errors that aren't tied to a specific tool call.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await agentcat.publishCustomEvent(mcpServer, "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
      }
  })
  ```

  ```go Go theme={null}
  mcpcat.PublishCustomEvent(s, "proj_abc123xyz", mcpcat.EventData{
      ResourceName: "rate_limit_hit",
      IsError:      true,
      Error:        map[string]any{"message": "Rate limit exceeded", "code": "RATE_LIMIT"},
      Parameters: map[string]any{
          "endpoint": "/api/search",
          "limit":    100,
      },
  })
  ```
</CodeGroup>

### Tracking User Milestones

Track when users reach key points in their journey, with duration to measure how long it took.

<CodeGroup>
  ```typescript TypeScript theme={null}
  await agentcat.publishCustomEvent(mcpServer, "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
  })
  ```

  ```go Go theme={null}
  mcpcat.PublishCustomEvent(s, "proj_abc123xyz", mcpcat.EventData{
      ResourceName: "onboarding_completed",
      Message:      "User finished all onboarding steps",
      Parameters: map[string]any{
          "stepsCompleted": 5,
      },
      Duration: 200000,
  })
  ```
</CodeGroup>