Event Meta Tags | Paygent Documentation

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

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

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

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

# 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