# Ads

Spend, impressions and clicks from the connected ad platforms, joined to the conversions they produced.

Source: https://sourceloop.ai/help/api/ads/

---

| Endpoint | Method | Path | Permission |
| --- | --- | --- | --- |
| Get ad performance | GET | `/v1/ads/performance` | `metrics:read` |

Base URL: `https://app.sourceloop.ai/api/v1`

## Get ad performance

`GET /v1/ads/performance`

Ad platform spend and delivery

Requires scope: `metrics:read`

`level` is REQUIRED. Spend is stored once per breakdown grain, so a query that
does not pin one, or that mixes two, multiplies it.

Metrics named `platform_*` are what the ad platform reports under its own
attribution window and view-through rules. They will not match Sourceloop
attributed conversions, and that difference is expected.

Amounts are in the AD ACCOUNT currency, which may differ from the workspace
currency; `meta.currency_source` says which you got.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `website` | string | no | Website domain, e.g. acme.com. Required only when the key covers more than one. |
| `period` | string | no | Plain-language period: "last 30 days", "yesterday", "July 2026", or "2026-07-01..2026-07-31". Ignored when from/to are given. |
| `level` | string | yes | Grain to report at. "campaign" is the usual view. |
| `metrics` | string | no | Comma-separated. One or more of: spend, impressions, clicks, platform_conversions, platform_revenue, ctr, cpc, cpm, platform_roas, platform_conversion_rate |
| `breakdown` | boolean | no | One row per item at that level. |
| `platform` | string | no |  |

### Responses

- `200` Ad rows
- `400` Something was wrong with the request or the credential.
- `429` Too many requests for this workspace in the current minute. Wait Retry-After seconds and repeat the request unchanged.

### Example (cURL)

```bash
curl -s -X GET "https://app.sourceloop.ai/api/v1/ads/performance?website=acme.com&period=last%2030%20days" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/ads/performance?website=acme.com&period=last%2030%20days",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.get(
    "https://app.sourceloop.ai/api/v1/ads/performance?website=acme.com&period=last%2030%20days",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```