> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Event Meta Tags

Event meta tags are optional key/value labels attached to individual usage and billing events (LLM calls, voice sessions, external costs).

## Dashboard filters

On **Agents** and **Customers**, use the *Event meta tags* field. Press Enter or comma after each filter. Multiple chips are combined with AND (all must match).

| You type      | Matches events where…                               |
| ------------- | --------------------------------------------------- |
| `env`         | Tag key env exists, or any value equals env         |
| `us-east`     | Tag key us-east exists, or any value equals us-east |
| `env:staging` | Exact pair env = staging                            |
| `env:`        | Key env exists (any value)                          |
| `:us-east`    | Any tag value equals us-east                        |

## Send tags from the Python SDK

### Manual usage (V2 API)

**`usage_with_meta_tags.py`**

```python title="usage_with_meta_tags.py"
from paygent_sdk import Client
from paygent_sdk.models import RawUsageData

client = Client("your-paygent-api-key")

client.send_usage_v2(
    "my-agent",
    "customer-123",
    "chat-message",
    RawUsageData(
        provider="Open AI",
        model="gpt-4o-mini",
        input_tokens=100,
        output_tokens=50,
    ),
    meta_tags={"env": "staging", "region": "eu"},
)
```

### Auto-patch (OpenAI, etc.)

**`openai_with_meta_tags.py`**

```python title="openai_with_meta_tags.py"
import paygent_sdk
from openai import OpenAI

paygent_sdk.init(api_key="your-paygent-api-key")
client = OpenAI()

client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hi"}],
    paygent_agent_id="my-agent",
    paygent_customer_id="customer-123",
    paygent_indicator="chat",
    paygent_meta_tags={"env": "staging", "team": "support"},
)
```

### External cost

**`external_cost_meta_tags.py`**

```python title="external_cost_meta_tags.py"
from paygent_sdk import Client
from paygent_sdk.models import ExternalCostData

client = Client("your-paygent-api-key")

client.send_external_cost(
    "my-agent",
    "customer-123",
    "telephony",
    ExternalCostData(
        name="outbound_call",
        external_cost_id="telephony_cost",
        meta_tags={"env": "staging", "channel": "voice"},
    ),
)
```

### Voice — session-level tags

Set tags once when the voice session starts; STT/LLM/TTS/STS events in that session inherit them.

**`voice_session_meta_tags.py`**

```python title="voice_session_meta_tags.py"
# Direct API
client.initialize_voice_session(
    session_id="sess-1",
    agent_id="my-agent",
    customer_id="customer-123",
    meta_tags={"env": "staging", "feature": "ivr"},
)

# LiveKit hook
from paygent_sdk.wrappers import LiveKitPaygentHook

hook = LiveKitPaygentHook(
    paygent_client=client,
    agent_id="my-agent",
    customer_id="customer-123",
    session_id="sess-1",
    meta_tags={"env": "staging"},
)
hook.attach(session)

# Vapi hook — tags go into call metadata for the webhook
from paygent_sdk.wrappers import VapiPaygentHook

hook = VapiPaygentHook(
    agent_id="my-agent",
    customer_id="customer-123",
    meta_tags={"env": "staging"},
)
hook.attach(vapi_client)
```

## Rules and limits

* Up to 20 tags per event
* Keys: letters, numbers, `_`, `-` (max 64 characters)
* Values: max 256 characters
* Invalid tags never block usage — they are skipped with a warning in SDK logs