> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/endpoints/publications/earnings.md).

# Earnings

## Earnings

Cross-cutting **earnings** aggregation for a publication, across its recommendations and offers. Earnings combine paid recommendation-referral commission (confirmed plus a confirmation-rate-estimated pending amount) and confirmed offer-conversion commission. Every figure is in US dollars.

The report takes one of three shapes (it never mixes them), controlled by `granularity` and `group_by`:

* `granularity=total`, no `group_by` — one overall figure.
* `granularity=total` with `group_by` — one figure per group, ranked highest-first.
* `granularity=daily`/`weekly`/`monthly` — one figure per time bucket.

### Get earnings

<mark style="color:blue;">`GET`</mark> `https://api.sparkloop.app/v3/publications/:publication_uuid/earnings`

**Path Parameters**

| Name                                                | Type   | Description             |
| --------------------------------------------------- | ------ | ----------------------- |
| publication\_uuid<mark style="color:red;">\*</mark> | String | The publication's UUID. |

**Query Parameters**

| Name        | Type   | Description                                                                                                                                                          |
| ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from        | String | Start date (`YYYY-MM-DD`). Defaults to 30 days ago.                                                                                                                  |
| to          | String | End date (`YYYY-MM-DD`). Defaults to today.                                                                                                                          |
| channel     | String | Restrict to a single referral channel (e.g. `signup_flow`, `recommendations_hub`). Unsupported values return `400` with the list of valid channels.                  |
| group\_by   | String | `utm_campaign`, `recommendation`, or `offer`. Only valid with `granularity=total`.                                                                                   |
| granularity | String | `total` (default), `daily`, `weekly`, or `monthly`.                                                                                                                  |
| expand      | String | Inline the promoted thing on each grouped row instead of a bare uuid: `recommended_publication` (with `group_by=recommendation`) or `offer` (with `group_by=offer`). |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "earnings": <Earnings Report Object>
}
```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  "error": "`group_by` is only supported with `granularity=total`."
}
```

{% endtab %}
{% endtabs %}