Spend API
List spend records (hourly)
Retrieve hourly spend records for a platform and time range.
GET
List hourly spend records
Headers
Query parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
hour_start_iso_begin | string (date-time) | The date range of a spend entries to search for - provide this or and a end date OR a date ONLY | ”1970-01-01T00:00:00-0000” |
hour_start_iso_end | string (date-time) | The date range of a spend entries to search for - provide this or and a start date OR a date ONLY | ”1970-01-01T01:00:00-0000” |
platform_account_id | string | The Ad Platform Account ID to search for, required | ”12345” |
campaign_id | string | The Ad Platform’s Campaign ID to search for | ”12345” |
adset_id | string | The Ad Platform’s Adset ID to search for | ”12345” |
ad_id | string | The Ad Platform’s Ad ID to search for | ”12345” |
page | integer | If Paginating - supply page number Required range: x >= 1Default: 1 | 1 |
page_size | integer | Results per page - Maximum of 1000 results per page Default: 1000 | 1000 |
Responses
200 response body
| Field | Type | Description |
|---|---|---|
data required | object[] | |
Field Type Description Example hour_start_iso requiredstring (date-time) The date-time of spend entry to upsert in UTC, required ”1970-01-01T00:00:00-0000”platform_account_idstring The Ad Platform Account ID to upsert, used for segregating ad objects per ad platform account Default: """12345”platform_name requiredstring The Ad Platform Name to upsert, required ”Facebook”campaign_id requiredstring The Ad Platform’s Campaign ID (utm_campaign, if known) to upsert, required ”12345”campaign_name requiredstring The Ad Platform Campaign Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as campaign_id”Banana Festival Awareness Campaign”adset_idstring The Ad Platform’s Adset ID (utm_term, if known) to upsert, defaults to ” if empty (not all platforms support adsets) Default: """12345”adset_namestring The Ad Platform Adset Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset_id - defaults to ” if emptyDefault: """Banana Adset”ad_idstring The Ad Platform’s Ad ID (utm_content, if known) to upsert, defaults to ” if empty (not all platforms support ads) Default: """12345”ad_namestring The Ad Platform Ad Name to upsert - will be as Ad Name in the Northbeam Dashboard - can be the same as adset_id - defaults to ” if emptyDefault: """Banana Ad”spend requirednumber Amount (in currency) spent on ad object to upsert, defaults to 0 if empty Required range: x >= 0123.5spend_currency requiredstring The Currency of the Spend per ISO 4217 to upsert, required Required string length: 3 - 3”USD”impressionsnumber The amount of impressions the ad object received on a given date, defaults to 0 if empty Required range: x >= 0Default: 0299clicksnumber The amount of clicks the ad object received on a given date, defaults to 0 if empty Required range: x >= 0Default: 00created_at requiredstring (date-time) updated_at requiredstring (date-time) | ||
page required | integer | |
page_size required | integer | |
total_pages required | integer | |
total_count required | integer |
401 response body
| Field | Type | Description |
|---|---|---|
errors | object[], nullable | |
message required | string | |
request_id | string (uuid), nullable |
422 response body
| Field | Type | Description |
|---|---|---|
errors | object[], nullable | |
message required | string | |
request_id | string (uuid), nullable |
4XX response body
| Field | Type | Description |
|---|---|---|
errors | object[], nullable | |
message required | string | |
request_id | string (uuid), nullable |
5XX response body
| Field | Type | Description |
|---|---|---|
errors | object[], nullable | |
message required | string | |
request_id | string (uuid), nullable |
Query Parameters
The date range of a spend entries to search for - provide this or and a end date OR a date ONLY
Example:
"1970-01-01T00:00:00-0000"
The date range of a spend entries to search for - provide this or and a start date OR a date ONLY
Example:
"1970-01-01T01:00:00-0000"
The Ad Platform Account ID to search for, required
Example:
"12345"
The Ad Platform's Campaign ID to search for
Example:
"12345"
The Ad Platform's Adset ID to search for
Example:
"12345"
The Ad Platform's Ad ID to search for
Example:
"12345"
If Paginating - supply page number
Required range:
x >= 1Example:
1
Results per page - Maximum of 1000 results per page
Example:
1000