docs.VoiceRun

Tags

Tags let you attach metadata to sessions as key-value pairs (e.g., location:us-east, campaign:summer-promo). Once tagged, you can filter and break down usage data by those dimensions using the Usage API.

Setting Tags#

Tags are set in your handler using context.set_data("tags", ...) and persisted with a ContextUpdateEvent.

from primfunctions.events import Event, StartEvent, TextToSpeechEvent, ContextUpdateEvent
from primfunctions.context import Context

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        # Tag the session
        context.set_data("tags", [
            "department:sales",
            "region:us-east",
        ])
        yield ContextUpdateEvent(context.serialize())

        yield TextToSpeechEvent(text="Hello!", voice="nova")

Tag Format#

Tags are a list of strings in key:value format:

["key1:value1", "key2:value2"]

Choose descriptive keys that represent the dimensions you want to analyze, such as department, region, campaign, location, or language.

Dynamic Tags#

Tags are often set dynamically based on session context rather than hardcoded. Building on the example above, you might know the department at session start but resolve the region later based on user input:

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        # Tag with what we know so far
        context.set_data("tags", [
            "department:sales",
        ])
        yield ContextUpdateEvent(context.serialize())

        yield TextToSpeechEvent(text="Which region are you calling from?", voice="nova")

    if isinstance(event, TextEvent):
        region = detect_region(event.data.get("text", ""))

        if region:
            # Add region to existing tags
            context.set_data("tags", [
                "department:sales",
                f"region:{region}",
            ])
            yield ContextUpdateEvent(context.serialize())

You can set tags at any point during the session. Tags set later in the conversation overwrite any previously set tags.

Querying Tagged Usage#

Once sessions are tagged, use the Usage by Tags endpoints to break down usage across those dimensions.

For example, if you tag sessions with department and region, you can query usage filtered to a specific department and see the breakdown by region:

GET /v1/usage/report/by-tags?startDate=2025-01-01&endDate=2025-01-31&tags={"department":"sales"}

This returns usage for all sessions tagged with department:sales, broken down by each unique tag combination (including region).

See Usage — Tag-Based Usage for full endpoint documentation.

Related#

tagssessionsanalyticsobservability