Margin Data API
Get margin trend
Returns time-series margin data (revenue - cost) with adaptive granularity: - <= 30 days: daily - 31-90 days: weekly - > 90 days: monthly Periods with no revenue and no cost activity are omitted from data_points rather than returned as zero values. Call it with a GET request to /margin-data/trend, authenticated with a restricted API key and the "revenue:read" scope.
GET https://api.bearlumen.com/v1/margin-data/trend
Returns time-series margin data (revenue - cost) with adaptive granularity: - <= 30 days: daily - 31-90 days: weekly - > 90 days: monthly Periods with no revenue and no cost activity are omitted from data_points rather than returned as zero values. Zero-fill client-side if you need a continuous series. Margin requires revenue data from your connected Stripe account; connect it in your dashboard under Settings then Integrations. Note that a not-yet-connected account and a genuine zero-revenue period both return "0", so verify the connection before interpreting zeros. If no revenue has been synced for a period, its revenue field returns "0" and margin_percent is null (division by zero is undefined). Revenue is recognized on an accrual basis: each revenue record's amount is attributed across its billing period. Costs are attributed to the time the usage event occurred. 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 revenue:read scope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
start_date | query | string | Yes | Start of date range (ISO 8601, inclusive). |
end_date | query | string | Yes | End of date range (ISO 8601, exclusive). |
end_user_id | query | string | No | Optional end user to filter by. Pass the end_user_id (UUID) returned by GET /margin-data/by-end-user. This is Bear Lumen's internal end-user ID, not the external ID you send on usage events. |
Response example
Success response (200):
{
"data_points": [
{
"cost": "0",
"date": "2026-05-15T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "522.3",
"date": "2026-05-16T00:00:00.000Z",
"margin_amount": "-275.9993548387096775",
"margin_percent": -112.06,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-17T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "336.48",
"date": "2026-05-18T00:00:00.000Z",
"margin_amount": "-90.1793548387096775",
"margin_percent": -36.61,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-19T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "241.06",
"date": "2026-05-20T00:00:00.000Z",
"margin_amount": "5.2406451612903225",
"margin_percent": 2.13,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-21T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-22T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "236.04",
"date": "2026-05-23T00:00:00.000Z",
"margin_amount": "10.2606451612903225",
"margin_percent": 4.17,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-24T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "381.68",
"date": "2026-05-25T00:00:00.000Z",
"margin_amount": "-135.3793548387096775",
"margin_percent": -54.97,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-26T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "190.84",
"date": "2026-05-27T00:00:00.000Z",
"margin_amount": "55.4606451612903225",
"margin_percent": 22.52,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-28T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-29T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-30T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
},
{
"cost": "0",
"date": "2026-05-31T00:00:00.000Z",
"margin_amount": "246.3006451612903225",
"margin_percent": 100,
"revenue": "246.3006451612903225"
}
],
"granularity": "daily"
}
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 query parameters. Check that start_date and end_date are valid ISO 8601 dates. |
401 | Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY. |
403 | API key lacks the revenue:read scope. Use a key that includes the revenue:read scope. |
422 | Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less. |
429 | Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header. |
Rate limits and retries
Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header.