> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python advertising reporting pipeline: should I use REST or MCP?

> Use Apostra's V3 HTTP API and the Python SDK for a deterministic reporting pipeline, and MCP for the agent that manages campaigns. Where v2 REST is still needed.

For a Python reporting pipeline, call Apostra's V3 HTTP API with the `apostra`
SDK (`python -m pip install apostra`) so the job runs on a schedule with fixed,
typed requests and no model in the loop. Use the V3 MCP for the agent that
plans and manages campaigns. Both work on the same account data and permissions.
You need REST rather than MCP for scheduled jobs, backend services and any step
where your code, not a model, picks the operation. A CSV download and a recurring
cloud-storage feed are not V3 operations; the table says where each lives.

## Which API for which job

| Job | Use | Why |
| - | - | - |
| Nightly delivery read into a warehouse | V3 HTTP API, `POST /api/v3/tools/get_delivery`, or the SDK | Fixed requests, API key or M2M token, no MCP session |
| An agent answers "how is this campaign doing?" | V3 MCP `get_delivery` | The model discovers the tool and its schema |
| An agent builds, stages and launches campaigns | V3 MCP | Typed tools with schemas the model can read |
| Send conversion events from your backend | V3 `save_event_source`, then `log_event`, over HTTP or MCP | Up to 10,000 events per call, deduplicated on retry |
| CSV download of aggregate campaign data | Not a V3 operation | Existing v2 integrations keep it until the v2 buyer API switches off on 1 December 2026. Plan around V3 reads instead |
| Recurring files into your own cloud storage | v2 Data Delivery | Configured on v2 today, not a V3 export tool. See [Build a reporting pipeline](https://docs.apostra.com/v3/reporting-pipeline.md) |

The two surfaces publish separate input contracts, and HTTP can be stricter.
Use the [OpenAPI document](https://docs.apostra.com/v3/http-api.md) for HTTP clients and `tools/list` for MCP
clients. The Python SDK is generated from the same OpenAPI document, and its
generated manifest lists the public V3 operations. Some administration, ingestion and lifecycle APIs remain on
v2.

## A first delivery read in Python

```python theme={null}
from apostra import Apostra

with Apostra() as api:
    status = api.get_status()
    delivery = api.get_delivery({
        'report': 'campaign_delivery',
        'metrics': ['impressions', 'clicks', 'spend', 'ctr'],
        'dimensions': ['date', 'campaign'],
        'range': {'startDate': '2026-11-01', 'endDate': '2026-11-07'},
        'filters': {'campaignId': 'your-campaign-id'},
    })
```

Keep the credential in your secret manager. The SDK reads `APOSTRA_API_KEY` from
the environment, or the sign-in from `apostra login` for local development.

## Limits your pipeline has to handle

* A date range is inclusive, in UTC, and at most 90 days. Lifetime reads use
  `range: {"lifetime": true}`.
* Follow every page the response returns before treating a window as complete.
* A metric a seller did not report comes back as unavailable, never as zero.
* Every row carries a `finality` label: Official, Snapshot or unavailable. Rows of
  different finality are not added together.
* Delivery is not real time. A successful response does not mean every seller has
  reported every event.
* A V3 MCP OAuth token is rejected on the HTTP API and the reverse. An M2M token
  works on the HTTP API only.

Rerun a completed window and confirm it replaces rows rather than appending
duplicates before you connect a dashboard. The checks are in
[Build a reporting pipeline](https://docs.apostra.com/v3/reporting-pipeline.md).

## When not to use Apostra

* You need reporting from one platform only and no cross-seller view. That
  platform's own reporting API, such as the Amazon Ads, Google Ads or Meta reporting
  APIs, is more direct.
* You need hourly figures. Buyer reporting is day-grain.
* You want a raw event feed with no aggregation. A CSV aggregate is not a raw
  event feed, and Data Delivery supports specific data types and cadences.

## Next step

```bash theme={null}
python -m pip install apostra
```

Then follow the [SDK quickstart](https://docs.apostra.com/v3/sdk-quickstart.md) to verify the account and read
delivery, and [Build a reporting pipeline](https://docs.apostra.com/v3/reporting-pipeline.md) for the
extraction job. Pair it with an agent by connecting a coding agent to
`https://api.apostra.com/mcp/v3` as in [Connect in five minutes](https://docs.apostra.com/v3/quickstart.md).

## Sources

* [V3 HTTP API](https://docs.apostra.com/v3/http-api.md), [SDK guide](https://docs.apostra.com/v3/sdk-guide.md) and
  [SDK quickstart](https://docs.apostra.com/v3/sdk-quickstart.md).
* [Build a reporting pipeline](https://docs.apostra.com/v3/reporting-pipeline.md) and
  [Authentication](https://docs.apostra.com/v3/authentication.md).
* [Move a v2 buyer REST integration to V3](https://docs.apostra.com/v3/migrate-from-v2-rest.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.