Attribution Data API

Get cost per declared outcome

Returns the true cost per unit of value: for every outcome your spans declare (see the tracing guide), completed, failed, and unresolved units side by side. Call it with a GET request to /attribution-data/by-outcome, authenticated with a restricted API key and the "costs:read" scope.

GET https://api.bearlumen.com/v1/attribution-data/by-outcome

Returns the true cost per unit of value: for every outcome your spans declare (see the tracing guide), completed, failed, and unresolved units side by side. Use this to price against real unit economics; the cost of runs that failed stays visible as its own line instead of inflating the completed average. A unit is one execution of an outcome-declaring span. Its cost is the full cost of that span's call subtree, plus the session's untraced events when the outcome span is the session's only root span. Retried units (same unit_key across attempts) count once while their cost sums across attempts; retried_unit_count reports how many units needed more than one attempt. The date range filters on when a unit RESOLVED (its completion or failure event), or on last activity for unresolved units, so a unit's cost may predate the range. Units that declared an outcome, never resolved, and have been inactive longer than unresolved_after_hours are reported as unresolved; terminal-less units younger than that threshold are treated as still running and excluded. Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.

Authentication and scopes

Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the costs:read scope.

Parameters

Name	In	Type	Required	Description
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive). Applies to unit resolution time, not to when the cost was incurred.
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).
`unresolved_after_hours`	query	`number (double)`	No	Hours of inactivity after which a terminal-less unit is reported as unresolved rather than still running. Whole number between 1 and 8760; default 24.

Response example

Success response (200):

{
  "items": [
    {
      "completed_cost": "4.46",
      "completed_count": 2,
      "cost_per_completed_unit": "2.23",
      "failed_cost": "0.78",
      "failed_count": 1,
      "outcome": "ticket_resolved",
      "retried_unit_count": 1,
      "unresolved_cost": "0.75",
      "unresolved_count": 1
    }
  ],
  "total_outcome_count": 1
}

Error codes

Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.

Status	When it happens
`400`	Invalid request data. Check that start_date is before end_date, both are valid ISO 8601 dates, and unresolved_after_hours is a whole number between 1 and 8760.
`401`	Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.
`403`	API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.
`429`	Rate limit or plan quota exceeded. Slow down and retry after the current window resets.

Rate limits and retries

Rate limit or plan quota exceeded. Slow down and retry after the current window resets.