Overview

Request Tags are free form, custom strings that can be included in request API calls for later reference and data correlation. Request Tags can be used to associate your AI costs with specific scenarios, use cases, steps in a Use Case, or any other custom string you need in your product.

Request Tags may contain alphanumeric characters, underscores, and hyphens. All tags are automatically converted to lowercase and any leading or trailing whitespace is removed.

For example, let's imagine you are making calls to several Resources to summarize documents across different users over time. By tagging all of these requests, Pay-i will associate the costs of these calls to that scenario, and will give you controls to view and pivot the data accordingly on the Pay-i dashboard.

Setting Request Tags

There are several ways to specify request tags, depending on your integration method:

Using Headers Directly

When sending requests directly to the API, you can specify any number of Request Tags using the optional header xProxy-Request-Tags, with a comma-separated list.

Using the Python SDK

The Python SDK provides multiple ways to set request tags with specific inheritance rules:

1. Global Request Tags

You can set global request tags that apply to all requests by using the config parameter in payi_instrument():

from payi.lib.instrument import payi_instrument

# Set global request tags for all requests
payi_instrument(config={
    "request_tags": ["global-tag-1", "global-tag-2"]
})

2. Context-Level Request Tags

You can set request tags for a specific context using the track_context() function:

from payi.lib.instrument import track_context

# Set request tags for all calls within this context
with track_context(request_tags=["context-tag-1", "context-tag-2"]):
    # Make API calls here
    # All calls will have the tags: "context-tag-1", "context-tag-2"

3. Request-Level Tags

You can also set request tags for individual API calls:

# Using extra_headers with AI provider clients
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"xproxy-request-tags": "request-tag-1,request-tag-2"}
)

Tag Inheritance Rules

The Python SDK follows these rules for request tag inheritance:

If request_tags=None: Tags are inherited from the parent context
If request_tags=[] (empty list): No inheritance occurs and tags are cleared
If tags are provided (len(request_tags) > 0): New tags are merged with parent context tags

Example of Inheritance

# Global level
payi_instrument(config={"request_tags": ["global"]})

# Context level - inherits and adds tags
with track_context(request_tags=["context"]):
    # This request has tags: "global", "context", "request"
    response1 = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello"}],
        extra_headers={"xproxy-request-tags": "request"}
    )
    
    # This request has tags: "global", "context"
    response2 = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello"}]
    )
    
    # Clear tags with empty list
    with track_context(request_tags=[]):
        # This request has no tags
        response3 = client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": "Hello"}]
        )

If you would like to understand the cost of a specific sequence of AI requests, see Use Cases.