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

1 from paygent_sdk import Client
2 from paygent_sdk.models import RawUsageData
3 
4 client = Client("your-paygent-api-key")
5 
6 client.send_usage_v2(
7     "my-agent",
8     "customer-123",
9     "chat-message",
10     RawUsageData(
11         provider="Open AI",
12         model="gpt-4o-mini",
13         input_tokens=100,
14         output_tokens=50,
15     ),
16     meta_tags={"env": "staging", "region": "eu"},
17 )

Auto-patch (OpenAI, etc.)

openai_with_meta_tags.py

1 import paygent_sdk
2 from openai import OpenAI
3 
4 paygent_sdk.init(api_key="your-paygent-api-key")
5 client = OpenAI()
6 
7 client.chat.completions.create(
8     model="gpt-4o-mini",
9     messages=[{"role": "user", "content": "Hi"}],
10     paygent_agent_id="my-agent",
11     paygent_customer_id="customer-123",
12     paygent_indicator="chat",
13     paygent_meta_tags={"env": "staging", "team": "support"},
14 )

External cost

external_cost_meta_tags.py

1 from paygent_sdk import Client
2 from paygent_sdk.models import ExternalCostData
3 
4 client = Client("your-paygent-api-key")
5 
6 client.send_external_cost(
7     "my-agent",
8     "customer-123",
9     "telephony",
10     ExternalCostData(
11         name="outbound_call",
12         external_cost_id="telephony_cost",
13         meta_tags={"env": "staging", "channel": "voice"},
14     ),
15 )

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

1 # Direct API
2 client.initialize_voice_session(
3     session_id="sess-1",
4     agent_id="my-agent",
5     customer_id="customer-123",
6     meta_tags={"env": "staging", "feature": "ivr"},
7 )
8 
9 # LiveKit hook
10 from paygent_sdk.wrappers import LiveKitPaygentHook
11 
12 hook = LiveKitPaygentHook(
13     paygent_client=client,
14     agent_id="my-agent",
15     customer_id="customer-123",
16     session_id="sess-1",
17     meta_tags={"env": "staging"},
18 )
19 hook.attach(session)
20 
21 # Vapi hook — tags go into call metadata for the webhook
22 from paygent_sdk.wrappers import VapiPaygentHook
23 
24 hook = VapiPaygentHook(
25     agent_id="my-agent",
26     customer_id="customer-123",
27     meta_tags={"env": "staging"},
28 )
29 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