Send attributed events

PREMIUM ADD-ON ✨Governance is available upon request only. Please contact us to get access to this premium feature.

You don’t need a new endpoint. Add the entity values to the properties of the events you already send to Lago, using your attribution keys.

Tag an event

curl --location --request POST "$LAGO_URL/api/v1/events" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "event": {
      "transaction_id": "evt_001",
      "external_subscription_id": "sub_123",
      "code": "llm_tokens",
      "properties": {
        "value": 10,
        "model": "opus",
        "department_id": "rnd",
        "team_id": "eng",
        "user_id": "alice",
        "api_key": "key_1"
      }
    }
  }'

Lago attributes this event to rnd, eng, alice and key_1 at ingestion. value and model keep their usual billing role: the same properties serve billing and attribution.

Send every level

Include the full chain on every event, for example department_id, team_id and user_id.

Lago doesn’t infer a parent from earlier events. An event with only user_id counts for alice, and is unattributed at the team and department levels.

How values are read

Keys are case-sensitive and must match an attribution key exactly.
If an entity has several keys, Lago uses the first one found in the event.
Values are read as text, up to 255 characters.
A missing, blank, too long or nested value (object, array) is ignored. The event is unattributed for that entity.

Edge cases

Case	Result
Event sent before governance was enabled	Unattributed. There is no backfill.
Attribution key added to an entity	Applies to new events only.
Event without any attribution property	Billed as usual, unattributed at every level.
Event sent twice with the same `transaction_id`	Billed once. Attributed usage can count it twice for a short while, until the copies are merged.

All delivery methods work, including batch and streaming.

Query attributed usage

Read usage and spend per entity.

Core concepts

Entities, attribution keys and roll-ups.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Quotes & Order Forms

Invoicing

Payments & Cash Collection

AI Agents and MCP

Data & Analytics

Revenue recognition

Resources

Send attributed events

Tag an event

Send every level

How values are read

Edge cases

Query attributed usage

Core concepts

​Tag an event

​Send every level

​How values are read

​Edge cases

Query attributed usage

Core concepts

Tag an event

Send every level

How values are read

Edge cases