# Campaigns

A Collective Audience™ ***campaign*** is an object/entity that is responsible of the delivery setup for creatives. Thanks to campaigns, the creatives are delivered according to

* editorial or semantical audiences
* budget
* time period
* contextual targeting
* ...

See [Campaigns section](../campaigns) to learn more about Collective Audience™ campaigns

## Campaign object in the Collective Audience™ open API

The campaign object in this openned API is represented by the following schema :

* **date** : the day of the statistics (present if `&by_day=true`)
* **campaign_id** : the identifier of the campaign
* **campaign_name** : the name of the campaign
* **insertion_id** : the identifier of the insertion (present if `&by_insertion=true`)
* **insertion_name** : the name of the insertion (present if `&by_insertion=true`)
* **content_id** : the identifier of the content (present if `&by_content=true`)
* **content_name** : the name of the content (present if `&by_content=true`)
* **advertiser_id** : the identifier of the advertiser
* **advertiser_name** : the name of the advertiser
* **impressions** : the number of impressions
* **visible_impressions** : the number of visible impressions
* **engagements** : the number of first clicks on creatives
* **votes** : the number of votes on creatives
* **clicks** : the number of exit clicks on creatives
* **click_through_rate** : click rate on visible impressions
* **form_submissions** : the number of forms that have been submitted by users
* **optin_submissions** : the number of optins that have been submitted by users
* **video_impressions** : number of video impressions
* **video_visible_impressions** : number of video visible impressions
* **video_start** : number of video starts
* **video_first_quartile** : number of video first quartiles (25% of video completion)
* **video_midpoint** : number of video midpoints (50% of video completion)
* **video_third_quartile** : number of video third quartiles (75% of video completion)
* **video_complete** : number of video completes (100% of video completion)
* **video_complete_rate** : number of video completes divided by number of video starts
* **billables** : number of events that are counted for invoicing
* **spent** : spent in your account currency

The entity name to pass after the base url is `campaigns`

```http
GET https://data.collectiveaudience.co/api/campaigns?api_key={yourToken}

RESPONSE LIST OF CAMPAIGNS
```


---

```http
GET https://data.collectiveaudience.co/api/campaigns/{campaign_id}?api_key={yourToken}

RESPONSE ONE CAMPAIGN ITEM identified by {campaign_id}
```

## Params

You can pass query params to the request

* `api_key` (**required**) : your api token
* `date_from` (**optional** default **yesterday**) : first day of statistics lookup (`YYYY-MM-DD`)
* `date_to` (**optional** default **yesterday** ): last day of statistics lookup (`YYYY-MM-DD`)
* `by_day` (**optional** default **false**) : breakdown by day
* `by_insertion` (**optional** default **false**) : breakdown by insertion
* `by_creative` (**optional** default **false**) : breakdown by creative

## Example

```http
GET https://data.collectiveaudience.co/api/campaigns/aaaaaaaaaaaaaaaaaaaaaaaa?api_key=some-api-key&date_from=2023-01-01&by_day=true
```

This request responds with a JSON list of items for the campaign `aaaaaaaaaaaaaaaaaaaaaaaa`. One item by day from the 1st of January, 2023 with the relevant statistics in each.