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

# Data API endpoints

> Find filters, response fields, and examples for each endpoint

Use the base URL `https://dialedapi.evomarketing.co/api/v1`. The examples use `YOUR_API_KEY` and Acme sample data. Replace the key with your own.

## Common parameters

These parameters apply to the JSON and CSV data endpoints. You can omit them to use the defaults.

| Parameter | Values | What it does |
| - | - | - |
| `start_date`, `end_date` | `YYYY-MM-DD` | Set an inclusive date range. Send both together. You can also send `period=custom`. |
| `period` | `24h`, `7d`, `30d`, `60d`, `90d`, `6m`, `ytd`, `all`, `custom` | Select a date range. Defaults to `all`. Use `custom` with both dates. Do not combine another period with dates. |
| `platform` | `instagram`, `tiktok`, `youtube`, `facebook` | Filter platforms. Separate several values with commas. Defaults to the platforms selected in your client hub. |
| `attribution` | `upload_date`, `view_date` | Defaults to `upload_date`. Upload date counts a placement's lifetime views on the day it was posted. View date counts views on the day they happened. |
| `campaign_id` | Comma-separated public campaign IDs | Limit results to campaigns your brand can see. Use the IDs from `/brand`. |
| `api_key` | Your API key | Use only when a tool cannot send an `Authorization` or `X-EVO-API-Key` header. |

`/openapi.json` is public and does not use these parameters.

## `GET /brand`

Get your brand details and available campaign IDs.

| Parameter | Use |
| - | - |
| Common parameters | Optional. See the table above. |

| `data` field | Meaning |
| - | - |
| `id`, `name` | Your brand's public ID and name. |
| `logo_url` | Brand logo URL, or `null`. |
| `default_platforms` | Platforms selected by default in your client hub. |
| `campaigns` | Visible campaigns. Each has `id`, `name`, `status`, `start_date`, and `end_date`. A date can be `null`. |
| `metrics_since` | First placement date, or `null`. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/brand"
```

```json theme={null}
{"data":{"id":"acme-public-id","name":"Acme","logo_url":null,"default_platforms":["instagram","tiktok"],"campaigns":[{"id":"spring-public-id","name":"Spring launch","status":"active","start_date":"2026-03-01","end_date":null}],"metrics_since":"2026-03-02"},"meta":{"brand":{"id":"acme-public-id","name":"Acme"},"start_date":"2026-03-02","end_date":"2026-09-29","platforms":["instagram","tiktok"],"attribution":"upload_date","generated_at":"2026-09-29T14:00:00Z"}}
```

## `GET /metrics/summary`

Get totals for your selected range.

| Parameter | Use |
| - | - |
| Common parameters | Optional. See the table above. |

| `data` field | Meaning |
| - | - |
| `posts` | Number of placements. |
| `views`, `likes`, `comments`, `shares` | Total activity. `shares` can be `null`. |
| `engagement_rate` | Engagement rate as a number. |
| `creators` | Number of creators. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/metrics/summary?period=30d"
```

```json theme={null}
{"data":{"posts":12,"views":245000,"likes":9800,"comments":410,"shares":220,"engagement_rate":0.0426,"creators":5},"meta":{"brand":{"id":"acme-public-id","name":"Acme"},"start_date":"2026-08-31","end_date":"2026-09-29","platforms":["instagram","tiktok"],"attribution":"upload_date","generated_at":"2026-09-29T14:00:00Z"}}
```

## `GET /metrics/daily`

Get one row per day in the selected range.

| Parameter | Values | Use |
| - | - | - |
| Common parameters | See above | Optional filters. |
| `view_type` | `incremental`, `cumulative` | Daily values or running totals. Defaults to `incremental`. |

| `data` row field | Meaning |
| - | - |
| `date` | Day in `YYYY-MM-DD` format. |
| `posts` | Placements counted for that day. |
| `views`, `likes`, `comments`, `shares` | Activity counted for that day. `shares` can be `null`. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/metrics/daily?start_date=2026-09-01&end_date=2026-09-02&attribution=view_date"
```

```json theme={null}
{"data":[{"date":"2026-09-01","posts":1,"views":1200,"likes":50,"comments":4,"shares":2},{"date":"2026-09-02","posts":0,"views":950,"likes":42,"comments":3,"shares":1}],"meta":{"brand":{"id":"acme-public-id","name":"Acme"},"start_date":"2026-09-01","end_date":"2026-09-02","platforms":["instagram","tiktok"],"attribution":"view_date","generated_at":"2026-09-29T14:00:00Z"}}
```

## `GET /posts`

Get placements in pages. Follow `pagination.next_cursor` while `pagination.has_more` is `true`.

| Parameter | Values | Use |
| - | - | - |
| Common parameters | See above | Optional filters. |
| `sort` | `recent`, `views`, `engagement` | Sort placements. Defaults to `recent`. |
| `limit` | `1` to `100` | Number per page. Defaults to `50`. |
| `cursor` | Cursor from `pagination.next_cursor` | Get the next page. |

| `data` row field | Meaning |
| - | - |
| `id` | Placement ID. |
| `url`, `thumbnail_url`, `caption` | Placement link, image, and caption. Each can be `null`. |
| `platform`, `posted_at` | Platform and posting time. |
| `campaign` | Campaign `id` and `name`. |
| `creator` | Creator `id`, `name`, and `handle`. Each can be `null`. |
| `views`, `likes`, `comments`, `shares`, `engagement_rate` | Placement activity. |
| `pagination.next_cursor`, `pagination.has_more` | Next page cursor and whether another page exists. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/posts?period=30d&sort=views&limit=1"
```

```json theme={null}
{"data":[{"id":"sample-placement-id","url":"https://www.instagram.com/p/sample/","platform":"instagram","caption":"Acme launch","thumbnail_url":null,"posted_at":"2026-09-12T15:00:00Z","campaign":{"id":"spring-public-id","name":"Spring launch"},"creator":{"id":"sample-creator-id","name":"Alex Example","handle":"@alexexample"},"views":25000,"likes":1000,"comments":40,"shares":20,"engagement_rate":0.0424}],"meta":{"brand":{"id":"acme-public-id","name":"Acme"},"start_date":"2026-08-31","end_date":"2026-09-29","platforms":["instagram","tiktok"],"attribution":"upload_date","generated_at":"2026-09-29T14:00:00Z"},"pagination":{"next_cursor":null,"has_more":false}}
```

## `GET /creators`

Get creator results in pages. Increase `page` while `pagination.has_more` is `true`.

| Parameter | Values | Use |
| - | - | - |
| Common parameters | See above | Optional filters. |
| `page` | Positive integer | Page number. Defaults to `1`. |
| `limit` | `1` to `100` | Number per page. Defaults to `50`. |

| `data` row field | Meaning |
| - | - |
| `id`, `name` | Creator ID (can be `null`) and name. |
| `handles` | Platform and handle pairs. |
| `platforms` | Creator platforms. |
| `posts`, `views`, `likes`, `comments`, `shares` | Placement count and activity. |
| `engagement_rate`, `avg_views` | Engagement rate and average views. |
| `followers` | Follower count, or `null`. |
| `pagination.page`, `pagination.page_size`, `pagination.total`, `pagination.total_pages`, `pagination.has_more` | Page details. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/creators?period=30d&page=1&limit=1"
```

```json theme={null}
{"data":[{"id":"sample-creator-id","name":"Alex Example","handles":[{"platform":"instagram","handle":"@alexexample"}],"platforms":["instagram"],"posts":3,"views":42000,"likes":1700,"comments":65,"shares":32,"engagement_rate":0.0428,"avg_views":14000,"followers":12000}],"meta":{"brand":{"id":"acme-public-id","name":"Acme"},"start_date":"2026-08-31","end_date":"2026-09-29","platforms":["instagram","tiktok"],"attribution":"upload_date","generated_at":"2026-09-29T14:00:00Z"},"pagination":{"page":1,"page_size":1,"total":1,"total_pages":1,"has_more":false}}
```

## CSV endpoints

CSV downloads use the same common filters as their JSON endpoints. CSV responses contain a header row and data rows. They do not contain the JSON `meta` or `pagination` fields.

| Endpoint | Extra parameters | Columns |
| - | - | - |
| `GET /metrics/daily.csv` | `view_type=incremental` or `view_type=cumulative` | `date`, `posts`, `views`, `likes`, `comments`, `shares` |
| `GET /posts.csv` | `sort=recent`, `sort=views`, or `sort=engagement` | `id`, `url`, `platform`, `caption`, `thumbnail_url`, `posted_at`, `campaign_id`, `campaign_name`, `creator_id`, `creator_name`, `creator_handle`, `views`, `likes`, `comments`, `shares`, `engagement_rate` |
| `GET /creators.csv` | Common filters | `id`, `name`, `handles`, `platforms`, `posts`, `views`, `likes`, `comments`, `shares`, `engagement_rate`, `avg_views`, `followers` |

`/posts.csv` includes up to 50,000 placements. In `/creators.csv`, `handles` and `platforms` are JSON text inside CSV cells.

### `GET /metrics/daily.csv`

| Parameter | Use |
| - | - |
| Common parameters | Optional. See the table above. |
| `view_type` | `incremental` or `cumulative`. Defaults to `incremental`. |

| CSV column | Meaning |
| - | - |
| `date`, `posts` | Day and placement count. |
| `views`, `likes`, `comments`, `shares` | Daily activity. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/metrics/daily.csv?period=7d" \
  -o evo-daily.csv
```

```csv theme={null}
date,posts,views,likes,comments,shares
2026-09-28,1,1200,50,4,2
```

### `GET /posts.csv`

| Parameter | Use |
| - | - |
| Common parameters | Optional. See the table above. |
| `sort` | `recent`, `views`, or `engagement`. Defaults to `recent`. |

| CSV column | Meaning |
| - | - |
| `id`, `url`, `platform`, `caption`, `thumbnail_url`, `posted_at` | Placement details. |
| `campaign_id`, `campaign_name` | Campaign details. |
| `creator_id`, `creator_name`, `creator_handle` | Creator details. |
| `views`, `likes`, `comments`, `shares`, `engagement_rate` | Placement activity. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/posts.csv?period=30d&sort=recent" \
  -o evo-posts.csv
```

```csv theme={null}
id,url,platform,caption,thumbnail_url,posted_at,campaign_id,campaign_name,creator_id,creator_name,creator_handle,views,likes,comments,shares,engagement_rate
sample-placement-id,https://www.instagram.com/p/sample/,instagram,Acme launch,,2026-09-12T15:00:00Z,spring-public-id,Spring launch,sample-creator-id,Alex Example,@alexexample,25000,1000,40,20,0.0424
```

### `GET /creators.csv`

| Parameter | Use |
| - | - |
| Common parameters | Optional. See the table above. |

| CSV column | Meaning |
| - | - |
| `id`, `name`, `handles`, `platforms` | Creator details. `handles` and `platforms` contain JSON text. |
| `posts`, `views`, `likes`, `comments`, `shares` | Placement count and activity. |
| `engagement_rate`, `avg_views`, `followers` | Engagement, average views, and followers. |

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dialedapi.evomarketing.co/api/v1/creators.csv?period=30d" \
  -o evo-creators.csv
```

```csv theme={null}
id,name,handles,platforms,posts,views,likes,comments,shares,engagement_rate,avg_views,followers
sample-creator-id,Alex Example,"[{""platform"":""instagram"",""handle"":""@alexexample""}]","[""instagram""]",3,42000,1700,65,32,0.0428,14000,12000
```

## `GET /openapi.json`

Download the public OpenAPI document. No key or parameters are needed.

| Parameter | Use |
| - | - |
| None | This endpoint is public. |

| Response field | Meaning |
| - | - |
| `openapi` | OpenAPI version. |
| `info` | API name, version, and description. |
| `servers` | API server URL. |
| `paths` | Available endpoints and their parameters. |
| `components.securitySchemes` | Supported key locations. |

```bash theme={null}
curl "https://dialedapi.evomarketing.co/api/v1/openapi.json" \
  -o evo-openapi.json
```

```json theme={null}
{"openapi":"3.1.0","info":{"title":"EVO Data API","version":"1.0.0","description":"Read only brand marketing data. Prefer an Authorization header or X-EVO-API-Key. Query keys can appear in logs and browser history."},"servers":[{"url":"https://dialedapi.evomarketing.co"}],"paths":{"/api/v1/brand":{"get":{"summary":"Brand and campaign metadata"}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer"}}}}
```