Billable Metrics

Billable metrics tell Paygent how to count usage before applying your price. Without one, every API call counts as a single unit. With one, you bill on tokens, hours, unique documents, peak concurrency, or a custom formula.

How billable metrics work

Three steps. You set up the meter once, link it to an agent indicator, then set your rate.

Flow: SDK sends meta_tags → Metric aggregates → Pricing applied → Customer billed

Without vs with a metric

Set up in the dashboard

Follow these three steps. Code integration comes after the meter is configured.

Step 1 — Create a billable metric

Sidebar → Billable Metrics → Create metric. Fill in basic info, pick your aggregation type, and optionally add rounding rules or filters.

Step 2 — Link to an indicator

On Agents → Step 2: Indicators, click Link billable metric and select your meter. Leave as None to keep billing per raw event.

Step 3 — Set pricing on the agent

Step 3: Pricing — your rate applies to the metered quantity, not event count.

Available pricing types:

• FLAT — $X per unit
• VOLUME — tiered rates
• GRADUATED — progressive tiers
• CREDITS — debit wallet

Send metaTags from the SDK

Billable metrics read properties from meta_tags on each usage event. For indicator-based / metered billing, use send_indicator — the same pattern as our revenue-only examples. Every Paygent usage function accepts meta tags.

1
import os
2
import paygent_sdk
3
4
paygent_sdk.init(os.getenv("PAYGENT_API_KEY"))
5
6
agent_id = "agent-premium-123"
7
customer_id = "customer-corp-456"
8
indicator_name = "inference"
9
10
# meta_tags keys must match your billable metric field names
11
tags = {"hours": "2.5"}
12
13
paygent_sdk.send_indicator(
14
    agent_id=agent_id,
15
    customer_id=customer_id,
16
    indicator=indicator_name,
17
    meta_tags=tags,
18
)

Python SDK functions that accept meta_tags

Real examples for every aggregation type

Each example shows the dashboard config, sample events, the resulting billed quantity, and a send_indicator call with the matching meta_tags. Property keys must match your metaTags exactly — they are case-sensitive.

Count — Count how many events match (optionally filtered)

Real-world product: Regional API gateway — bill only for requests routed to us-east-1, not every global call.

Dashboard setup:

• Aggregation: Count

• Filter: region = us-east-1

• Identifier: us_east_requests

• Events this month: 50 events worldwide, 12 with region=us-east-1

• Billed quantity: 12 units billed (only matching events)

1
import paygent_sdk
2
3
paygent_sdk.init(api_key="your-paygent-api-key")
4
5
paygent_sdk.send_indicator(
6
    agent_id="api-gateway",
7
    customer_id=customer_id,
8
    indicator="api-request",
9
    meta_tags={"region": "us-east-1", "path": "/v1/chat"},
10
)

Sum — Add up a numeric property from every event

Real-world product: GPU inference platform — jobs range from 0.2 to 48 GPU-hours. Bill on actual compute, not call count.

Dashboard setup:

• Aggregation: Sum

• Aggregate on: Unique field → hours

• Identifier: gpu_hours

• Events this month: Job A: 0.2 hrs · Job B: 12 hrs · Job C: 48 hrs

• Billed quantity: 60.2 GPU-hours billed

1
import paygent_sdk
2
3
paygent_sdk.init(api_key="your-paygent-api-key")
4
5
paygent_sdk.send_indicator(
6
    agent_id="gpu-agent",
7
    customer_id=customer_id,
8
    indicator="inference",
9
    meta_tags={"hours": str(gpu_hours)},
10
)

Max — Bill on the highest value seen in the billing period

Real-world product: Realtime collaboration tool — charge based on peak concurrent users, not every heartbeat event.

Dashboard setup:

• Aggregation: Max

• Field: concurrent_users

• Identifier: peak_concurrent_users

• Events this month: Mon: 45 users · Wed: 120 users · Fri: 88 users

• Billed quantity: 120 units billed (peak for the period)

1
import paygent_sdk
2
3
paygent_sdk.init(api_key="your-paygent-api-key")
4
5
paygent_sdk.send_indicator(
6
    agent_id="collab-agent",
7
    customer_id=customer_id,
8
    indicator="presence-ping",
9
    meta_tags={"concurrent_users": str(active_count)},
10
)

Unique count — Count how many distinct values appear for a property

Real-world product: Document intelligence SaaS — charge per unique document analyzed, even if the same doc is re-processed multiple times.

Dashboard setup:

• Aggregation: Unique count

• Aggregate on: Unique field → document_id

• Identifier: documents_processed

• Events this month: doc-101 processed 3× · doc-202 processed 1× · doc-303 processed 2×

• Billed quantity: 3 unique documents billed (not 6 events)

1
import paygent_sdk
2
3
paygent_sdk.init(api_key="your-paygent-api-key")
4
5
paygent_sdk.send_indicator(
6
    agent_id="doc-agent",
7
    customer_id=customer_id,
8
    indicator="analyze",
9
    meta_tags={"document_id": "doc-101", "pages": "24"},
10
)
11
12
# Same document_id sent again → still 1 unique doc for the period

Latest — Use the most recent value received in the period

Real-world product: Seat-based AI workspace — customer adds and removes seats throughout the month. Bill on the latest seat count snapshot.

Dashboard setup:

• Aggregation: Latest

• Field: seat_count

• Identifier: active_seats

• Events this month: Week 1: 10 seats · Week 3: 25 seats · Week 4: 22 seats

• Billed quantity: 22 units billed (latest value)

1
import paygent_sdk
2
3
paygent_sdk.init(api_key="your-paygent-api-key")
4
5
paygent_sdk.send_indicator(
6
    agent_id="workspace-agent",
7
    customer_id=customer_id,
8
    indicator="seat-sync",
9
    meta_tags={"seat_count": str(current_seats)},
10
)

Custom expression — Compute a value with a formula before summing

Real-world product: Distributed inference cluster — bill on effective tokens (tokens × replica count), not raw tokens alone.

Dashboard setup:

• Aggregation: Sum

• Aggregate on: Custom expression

• Expression: event.properties.tokens * event.properties.replicas

• Result field: calculation_result

• Identifier: effective_tokens

• Events this month: Run 1: 1,000 tokens × 4 replicas · Run 2: 500 tokens × 2 replicas

• Billed quantity: 5,000 units billed (4000 + 1000)

1
import paygent_sdk
2
3
paygent_sdk.init(api_key="your-paygent-api-key")
4
5
paygent_sdk.send_indicator(
6
    agent_id="cluster-agent",
7
    customer_id=customer_id,
8
    indicator="inference",
9
    meta_tags={"tokens": "1000", "replicas": "4"},
10
)
11
12
# Custom expression evaluates: 1000 * 4 = 4000 per event