Read a publisher's earnings

GET /v1/actions/publishers/{namespace}/earnings
One month of what the namespace's hosted tools earned: the calls other organizations made, the gross of the publisher prices charged, B3OS's cut and the net, with the rate in force and why (take). Calls by the publisher's own organization are left out. Daily totals per tool are all a publisher sees: never a customer, a call or an error text. Only the organization the publisher list names as the namespace's owner may read it; to anyone else it is 404. Needs the actions.tools flag. Amounts are accrued: a record of what was sold. Nothing is paid out by B3OS's software in this version.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token)

Path Parameters

namespace string required path
Max length 100Pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$
Example: "io.b3os"

Query Parameters

period string optional query
The UTC calendar month, YYYY-MM. Default the current month.
Pattern ^[0-9]{4}-(0[1-9]|1[0-2])$

Responses

200 The month's earnings line.
application/json
object string REQUIRED
Values publisher_earnings
namespace string REQUIRED
period string REQUIRED
calls integer REQUIRED
gross_micro_usd integer REQUIRED
fee_micro_usd integer REQUIRED
net_micro_usd integer REQUIRED
take object REQUIRED
rate number REQUIRED
B3OS's share of the publisher's price in force, 0 (founding) or the standard rate (0.2 under the terms decided on 2026-11-11; the edge's MARKETPLACE_TAKE_TERMS can change it).
reason string REQUIRED
Values founding standard_after_12_months standard_after_1000_usd
first_priced_call_on string (date) | null REQUIRED
The UTC day of the publisher's first priced call by another organization; null before it.
founding_ends_on string (date) | null REQUIRED
Twelve calendar months after first_priced_call_on, the latest day the founding rate can end.
standard_since string (date) | null REQUIRED
The UTC day the 20% rate began; null while the founding rate is in force.
sales_to_date_micro_usd integer REQUIRED
Every sale to other organizations up to the end of the period.
parts object[] REQUIRED
Array of:
rate number REQUIRED
gross_micro_usd integer REQUIRED
fee_micro_usd integer REQUIRED
status string REQUIRED
Values accrued
400 The request failed validation (invalid_request, invalid_url).
401 Missing, malformed, expired or revoked credentials (unauthorized).
403 Authenticated but not allowed (forbidden, egress_denied).
404 The object does not exist or belongs to another project.
429 A rate, concurrency or quota limit applies (rate_limited, concurrency_limited, quota_exceeded).
500 Something failed inside B3OS (internal). Retry with backoff.
503 The node or the product is not available right now (node_unavailable, product_unavailable, capacity_unavailable). 
curl -X GET 'https://beta-api.b3os.org/v1/actions/publishers/io.b3os/earnings' \  -H 'Authorization: Bearer YOUR_API_TOKEN'
const response = await fetch('https://beta-api.b3os.org/v1/actions/publishers/io.b3os/earnings', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/actions/publishers/io.b3os/earnings', headers=headers)print(response.json())
200 Response 
{  "object": "publisher_earnings",  "namespace": "com.example.tools",  "period": "2026-11",  "calls": 615,  "gross_micro_usd": 1230000,  "fee_micro_usd": 0,  "net_micro_usd": 1230000,  "take": {    "rate": 0,    "reason": "founding",    "first_priced_call_on": "2026-11-12",    "founding_ends_on": "2027-11-12",    "standard_since": null,    "sales_to_date_micro_usd": 1230000  },  "parts": [    {      "rate": 0,      "gross_micro_usd": 1230000,      "fee_micro_usd": 0    }  ],  "status": "accrued"}
Previous Check for a hosted tool's archive
Next List connections
Ask a question... ⌘I