Cost attributed signals

Prerequisites

• A Paid API key.
• The Paid SDK installed in the service that emits signals and makes AI provider calls.
• Cost traces working for the AI call you want to attribute.
• Optional: customers and products with stable external IDs for attribution. You can also create them through the Products API and Customers API.

Track the AI cost behind each signal

Knowing the cost behind each signal helps you understand your margins. This combines the previous two steps (signals and cost traces) with a dedicated API call that links an agent action to the AI costs captured in the same tracing context.

The one requirement: send the signal from inside a paid_tracing context where your AI calls run.

1
from openai import OpenAI
2
from paid.tracing import initialize_tracing, paid_autoinstrument, paid_tracing, cost_attributed_signal
3
4
initialize_tracing(api_key="PAID_API_KEY")
5
paid_autoinstrument(libraries=["openai"]) # or leave empty to autoinstrument all libraries
6
7
openai_client = OpenAI(api_key="OPENAI_API_KEY")
8
9
with paid_tracing("your_external_customer_id", external_product_id="your_external_product_id"):
10
    # ... your business logic, occasional AI calls ...
11
    openai_client.chat.completions.create(
12
        model="gpt-4o-mini",
13
        messages=[{"role": "user", "content": "Summarize this order."}],
14
    )
15
    # ... your business logic, occasional AI calls ...
16
17
    # emit a signal (order relative to the AI call doesn't matter)
18
    res = cost_attributed_signal(
19
        event_name="email_sent",
20
        data={"some_data": "some_value"},
21
    )
22
    print("Signal sent:", res)

Consuming multiple credits and tracking users

Cost-attributed signals support the same data fields as regular signals. Pass quantity to consume more than one credit per signal, and include external_user_id to route credit spend to a specific user’s seat balance:

1
cost_attributed_signal(
2
    event_name="document_processed",
3
    data={
4
        "quantity": 5,
5
        "external_user_id": "usr_jane_doe",
6
        "pages": 47,
7
    },
8
)

See First signals for details on dynamic credit consumption and user-level tracking for per-user attribution.