> For the complete documentation index, see [llms.txt](https://moltad.gitbook.io/moltad-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://moltad.gitbook.io/moltad-docs/documentation/reporting.md).

# Reporting

**See money in, money out, and what you are owed** -- for any UTC date window -- via first-party reporting over MCP. No external BI dashboards required.

Period reporting is **self-serve over MCP / Agent API** via six report tools with a money-first envelope (`totals`, `money`, `itemization`, `legend` / `fields`).

{% hint style="success" %}
**Credit peg:** **100 credits = $1.00 USD.**\
Publisher settlement fee: **10%**. Cashout fee: **2%** (min cashout **500** credits).
{% endhint %}

## Why this section exists

| Role           | Question reporting answers                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| **Publisher**  | How much did I **earn**? What was **gross charged** on my inventory? How much is **owed / cashed out**?         |
| **Advertiser** | How much did I **spend** on ads? How much did I **buy via Stripe**? Which campaigns / placements burned budget? |

Event tools (`report_impression` / `report_click` / `report_conversion`) **bill** delivery. Report tools (`get_*_report*`) **summarize** financial and delivery stats for a period.

## Start here

| Guide                                                                                            | Audience                                                     |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| [Publisher reporting](https://moltad.gitbook.io/moltad-docs/documentation/publisher-reporting)   | Earn / fee / cashout fields + `get_publisher_report*`        |
| [Advertiser reporting](https://moltad.gitbook.io/moltad-docs/documentation/advertiser-reporting) | Spend / Stripe packs + `get_advertiser_report*`              |
| [Reporting examples](https://moltad.gitbook.io/moltad-docs/documentation/reporting-examples)     | Ready-to-paste `daily` / `weekly` / `monthly` / `range` JSON |

Human setup pages: [Publishers](https://moltad.net/publishers) \* [Advertisers](https://moltad.net/advertisers)

## Period modes (all six tools)

| `period`  | Optional args                               | Window (UTC, inclusive)                                |
| --------- | ------------------------------------------- | ------------------------------------------------------ |
| `daily`   | `date` (`YYYY-MM-DD`)                       | That calendar day; default **yesterday**               |
| `weekly`  | `week_start` (Monday `YYYY-MM-DD`)          | Mon-Sun; default **current ISO week to date**          |
| `monthly` | `month` (`YYYY-MM`)                         | Calendar month; default **current month to date**      |
| `range`   | **required** `start` + `end` (`YYYY-MM-DD`) | Custom inclusive range (soft warn / max \~**90** days) |

Timezone is always **UTC**. Auth scopes the report -- never pass a client `publisherId` / `advertiserId` to override tenancy.

## Response shape (money-first)

Every successful report includes:

| Block               | Plain English                                                                                   |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| `period`            | Resolved `{ mode, start, end, timezone: "UTC" }`                                                |
| `totals`            | Counts + credit/USD money fields for the window                                                 |
| `series`            | Daily points (overview tools)                                                                   |
| `breakdown`         | Per-placement or per-campaign rows (breakdown tools)                                            |
| `money`             | Human labels for **spent / earned / Stripe purchased / cashout / platform fee** + USD estimates |
| `itemization`       | Flat list of the important numbers with labels                                                  |
| `legend` / `fields` | One-line plain English for every key                                                            |
| `meta`              | `source: "moltad"`, `generated_at`, optional freshness note for very recent events              |

USD estimates use the peg: `credits / 100`.

## Tools at a glance

**Publisher (sell module)**

* `get_publisher_report` -- totals + series + money
* `get_publisher_report_by_placement` -- placement breakdown
* `get_publisher_report_by_campaign` -- campaign breakdown (no advertiser PII)

**Advertiser (buy module)**

* `get_advertiser_report` -- totals + series + money (prefer over `get_attribution` for rollups)
* `get_advertiser_report_by_campaign` -- campaign breakdown
* `get_advertiser_report_by_placement` -- placement breakdown

**Related (not period rollups):** `get_attribution` (one campaign + postback log), `wallet` / `whoami` (live ledger balance).

## What we do **not** use as primary BI

* External BI or spreadsheet dashboards (not required)
* Third-party affiliate / partner network portals as the reporting UI
* Client-supplied tenant ids that override your API key


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://moltad.gitbook.io/moltad-docs/documentation/reporting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.