[Tenjin API Reference](https://api-docs.tenjin.com/llms.txt) › [Reporting Metrics API](https://api-docs.tenjin.com/reporting-metrics-api.md) › Pull a spend report - Reporting Metrics API OpenAPI spec: https://api-docs.tenjin.com/openapi/reporting-metrics-api.json # Pull a spend report - **Method:** `GET` - **Path:** `/v2/reports/spend` - **Operation ID:** `get_reports_spend` - **Tags:** Reporting Metrics Columns of a row by group_by, besides `date` (absent with `granularity=totals-daily`) and the requested metrics: | group_by | Columns | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `app` | `app_id`, `name`, `icon_url`, `platform`, `bundle_id`, `store_id` | | `channel` | `ad_network_id`, `name`, `icon_url`, `short_id`, `custom` | | `campaign` | `campaign_id`, `name`, `icon_url`, the app columns (`app_id`, `app_name`, `app_icon_url`, `platform`, `bundle_id`, `store_id`) and the channel columns (`ad_network_id`, `ad_network_name`, `ad_network_icon_url`) | | `creative` | `creative_id`, `name`, `remote_creative_id`, the app columns and the channel columns | | `country` | `country`, `name` | | `site` | `site_id`, `name` | | `channel,app` | `ad_network_id`, `app_id`, the app columns and the channel columns | | `channel,app,country` | the `channel,app` columns and `country` | | `campaign,country` | the `campaign` columns and `country` | | any other combination | `name`: the ids joined with `-`, and the id column of each value with its columns: for `app`, the app columns; for `channel`, `ad_network_name`, `ad_network_icon_url`, `ad_network_short_id`, `ad_network_custom`; for `campaign`, `campaign_name`, `campaign_icon_url`, the app columns and the channel columns; for `creative`, `creative_name`, `remote_creative_id`, the app columns and the channel columns | A group_by with `campaign` or `creative` leaves out `channel` and `app`, which they determine: `channel,campaign` returns the `campaign` columns. ## Effective servers - `https://api.tenjin.com` ## Authentication - **Bearer**: HTTP bearer (`JWT`) Generate an access token on the [Access Tokens](https://dashboard.tenjin.com/dashboard/access_tokens) page of the Tenjin dashboard and send it as `Authorization: Bearer `. [API access tokens](https://tenjin.com/docs/api-access-tokens/) explains them. ## Query parameters - **`start_date`**: `string`, format: `date` First day to include, YYYY-MM-DD. Defaults to 30 days before today - **`end_date`**: `string`, format: `date` Last day to include, YYYY-MM-DD. Defaults to today - **`app_ids`**: `array of string`, explode: `false` Ids of the apps to report on, comma-separated; all accessible apps when blank - **`channel_ids`**: `array of integer`, explode: `false` Ids of the channels to report on, comma-separated; all channels when blank - **`granularity`**: `string`, possible values: `"daily", "weekly", "monthly", "totals-daily"`, default: `"daily"` Period of each row. With `totals-daily`, one row covers the whole date range - **`metrics`**: `array of string`, default: `["spend","impressions","clicks","installs","cpi","ctr","cvr","tcpi","tracked_installs"]`, explode: `false` Metrics to report, comma-separated: any of the [Metric Definitions](https://api-docs.tenjin.com/metric_definitions#spend) and the organization's `z_` custom metrics - **`metric_filters`**: `array of string`, explode: `false` Keep only rows where every filter holds. A filter is metric:op:value; op is gt, gte, lt, lte or eq - **`omit_blank_rows`**: `boolean` Drop rows where every requested metric is zero or null - **`ad_network_ids`**: `integer` Deprecated: use channel_ids. One ad network id, or several as `ad_network_ids[]`; ignored when channel_ids is sent - **`platforms`**: `string` Ignored; returned unchanged in meta.platforms - **`campaign_ids`**: `string` Ignored; returned unchanged in meta.campaign_ids - **`cohort_strategy`**: `string` RELATIVE or ABSOLUTE, in any case; defaults to the user's cohort strategy setting - **`countries`**: `array of string`, explode: `false` Keep only these countries: two-letter country codes such as `US`, and `UN` for an unknown country - **`group_by`**: `array`, default: `["app"]`, explode: `false` Dimensions to group the rows by, comma-separated; any combination of them **Array of:** `string`, possible values: `"channel", "app", "country", "campaign", "site", "creative"` - **`page`**: `integer`, default: `1` Page of results to fetch. - **`per_page`**: `integer`, default: `100`, minimum: `0`, maximum: `1000` Number of results to return per page. ## Responses ### 200 The report **Headers:** - **`Link`** URLs of the first, previous, next and last pages (RFC 8288); sent only when the list has more than one page `string` - **`Total`** Number of items on all pages `integer` - **`Per-Page`** Number of items per page `integer` **Content type:** `application/json` schema: `SpendReportDocument` - **`data` (required)**: `array` **Items:** schema: `SpendReportResource` - **`attributes` (required)**: `object` The dimension columns of the group_by, and the requested metrics: any of the [Metric Definitions](https://api-docs.tenjin.com/metric_definitions#spend) and the organization's z\_ custom metrics. Unknown metric names are left out. - **`ad_network_custom`**: `boolean` Whether the channel is a custom one. A group_by that includes channel and country or site, without campaign or creative, except channel,app,country - **`ad_network_icon_url`**: `string | null` Icon URL of the channel. A group_by that includes channel, campaign or creative, except channel alone - **`ad_network_id`**: `integer | null` Id of the channel. A group_by that includes channel, campaign or creative - **`ad_network_name`**: `string | null` Name of the channel. A group_by that includes channel, campaign or creative, except channel alone - **`ad_network_short_id`**: `string | null` URL-safe id of the channel. A group_by that includes channel and country or site, without campaign or creative, except channel,app,country - **`app_icon_url`**: `string | null` Icon URL of the app. A group_by that includes app, campaign or creative, except app alone - **`app_id`**: `string | null`, format: `uuid` Id of the app. A group_by that includes app, campaign or creative - **`app_name`**: `string | null` Name of the app. A group_by that includes app, campaign or creative, except app alone - **`bundle_id`**: `string | null` Bundle id of the app in its store. A group_by that includes app, campaign or creative - **`campaign_icon_url`**: `string | null` Icon URL of the campaign. A group_by that includes campaign and site or creative - **`campaign_id`**: `string`, format: `uuid` Id of the campaign. A group_by that includes campaign - **`campaign_name`**: `string | null` Name of the campaign. A group_by that includes campaign and site or creative - **`country`**: `string` ISO country code. A group_by that includes country - **`creative_id`**: `string`, format: `uuid` Id of the creative. A group_by that includes creative - **`creative_name`**: `string | null` Name of the creative. A group_by that includes creative and campaign, country or site - **`custom`**: `boolean | null` Whether the channel is a custom one. Group by channel - **`date`**: `string`, format: `date` First day of the period; absent with granularity=totals-daily - **`icon_url`**: `string | null` Icon URL of the app, channel or campaign. Group by app or channel alone, or a group_by that includes campaign, without site or creative - **`name`**: `string | null` Name of the app, channel, campaign or creative; the country code or site id. Group by app, channel, campaign, creative, country or site, and the campaign name for campaign,country. Absent for channel,app and channel,app,country. A group_by with campaign or creative ignores channel and app. For any other combination, the ids joined with `-`, such as `3-US` - **`platform`**: `string | null`, possible values: `"amazon", "android", "android_other", "ios", "windows", "unspecified", null` Platform of the app. A group_by that includes app, campaign or creative - **`remote_creative_id`**: `string | null` Id of the creative on the ad network. A group_by that includes creative - **`short_id`**: `string | null` URL-safe id of the channel. Group by channel - **`site_id`**: `string` Id of the site. A group_by that includes site - **`store_id`**: `string | null` Id of the app in its store. A group_by that includes app, campaign or creative **Additional properties:** `number | null`, format: `double` - **`id` (required)**: `string` - **`type` (required)**: `string`, possible values: `"report"` - **`links` (required)**: `object`, schema: `Links` - **`self` (required)**: `string`, format: `uri` URL of this request - **`first`**: `string`, format: `uri` URL of the first page of a list - **`last`**: `string`, format: `uri` URL of the last page of a list - **`next`**: `string`, format: `uri` URL of the next page of a list - **`prev`**: `string`, format: `uri` URL of the previous page of a list - **`meta` (required)**: `object`, schema: `SpendReportMeta` - **`ad_network_ids` (required)**: `(array of integer) | string | (array of string)` The channel_ids param, or the deprecated ad_network_ids param as sent: a string or an array of strings - **`app_ids` (required)**: `array of string` The app_ids param - **`campaign_ids` (required)**: `string | (array of string)` The deprecated campaign_ids param as sent; empty when not sent - **`count` (required)**: `integer` Number of rows on all pages - **`countries` (required)**: `array of string` The countries param - **`end_date` (required)**: `string`, format: `date` The end_date param, or its default - **`granularity` (required)**: `string`, possible values: `"daily", "weekly", "monthly", "totals-daily"` The granularity param, or its default - **`group_by` (required)**: `string | null`, possible values: `"ad_network_id", "app_id", "campaign_id", "country", "site_id", "creative_id", "ad_network_app", "ad_network_app_country", "channel_country", "app_country", "campaign_country", "campaign_creative", "campaign_site", "creative_country", "creative_site", null` Internal dimension name for one dimension, a name for some combinations, or null for any other combination - **`metrics` (required)**: `array of string` The requested metrics - **`organization_id` (required)**: `string`, format: `uuid` Id of your organization - **`per_page` (required)**: `integer` Number of rows per page - **`platforms` (required)**: `string | (array of string)` The deprecated platforms param as sent; empty when not sent - **`start_date` (required)**: `string`, format: `date` The start_date param, or its default **Example: Group by app** ```json { "data": [ { "id": "2026-08-25,cdeefd60-238c-4818-a948-44f3351f0b47", "type": "report", "attributes": { "date": "2026-08-25", "app_id": "cdeefd60-238c-4818-a948-44f3351f0b47", "spend": 843.36, "installs": 2590, "clicks": 8301, "impressions": 423383, "name": "Alpha", "icon_url": "/default_app_icon.png", "bundle_id": "com.example.alpha", "store_id": "2000000001", "platform": "ios" } }, { "id": "2026-08-25,6f08bd91-f376-4e19-b4b1-1b1c9f6f99dd", "type": "report", "attributes": { "date": "2026-08-25", "app_id": "6f08bd91-f376-4e19-b4b1-1b1c9f6f99dd", "spend": 567.86, "installs": 1327, "clicks": 4157, "impressions": 287763, "name": "Bravo", "icon_url": "/default_app_icon.png", "bundle_id": "com.example.bravo", "store_id": "com.example.bravo", "platform": "android" } } ], "links": { "self": "https://api.tenjin.com/v2/reports/spend?start_date=2026-08-25&end_date=2026-08-31&group_by=app&granularity=daily&metrics=spend%2Cinstalls%2Cclicks%2Cimpressions" }, "meta": { "count": 14, "per_page": 100, "start_date": "2026-08-25", "end_date": "2026-08-31", "granularity": "daily", "metrics": [ "spend", "installs", "clicks", "impressions" ], "organization_id": "48328cd8-8a31-42a0-baa6-6724783f90e9", "app_ids": [], "ad_network_ids": [], "group_by": "app_id", "countries": [], "campaign_ids": [], "platforms": [] } } ``` **Example: Group by channel** ```json { "data": [ { "id": "2026-08-25,900011", "type": "report", "attributes": { "date": "2026-08-25", "ad_network_id": 900011, "spend": 1125.59, "impressions": 566074, "clicks": 8978, "installs": 3007, "cpi": 0.37432324575989356, "ctr": 1.5860117228489559, "cvr": 33.49298284695924, "tcpi": 0.3581259942729876, "tracked_installs": 3143, "name": "Network One", "icon_url": "", "short_id": "network_one", "custom": false } }, { "id": "2026-08-25,900012", "type": "report", "attributes": { "date": "2026-08-25", "ad_network_id": 900012, "spend": 285.63, "impressions": 145072, "clicks": 3480, "installs": 910, "cpi": 0.3138791208791209, "ctr": 2.3988088673210544, "cvr": 26.149425287356323, "tcpi": 0.3661923076923077, "tracked_installs": 780, "name": "Network Two Account", "icon_url": "", "short_id": "network_two", "custom": true } } ], "links": { "self": "https://api.tenjin.com/v2/reports/spend?start_date=2026-08-25&end_date=2026-08-31&group_by=channel&granularity=daily" }, "meta": { "count": 14, "per_page": 100, "start_date": "2026-08-25", "end_date": "2026-08-31", "granularity": "daily", "metrics": [ "spend", "impressions", "clicks", "installs", "cpi", "ctr", "cvr", "tcpi", "tracked_installs" ], "organization_id": "2e6bca27-ad83-4280-b807-82e800acdfcf", "app_ids": [], "ad_network_ids": [], "group_by": "ad_network_id", "countries": [], "campaign_ids": [], "platforms": [] } } ``` **Example: Group by campaign** ```json { "data": [ { "id": "2026-08-25,751bed7c-9433-4108-88f5-50cba7ad8ce6", "type": "report", "attributes": { "date": "2026-08-25", "campaign_id": "751bed7c-9433-4108-88f5-50cba7ad8ce6", "spend": 376.59000000000003, "impressions": 158201, "clicks": 2687, "installs": 875, "cpi": 0.43038857142857145, "ctr": 1.6984721967623466, "cvr": 32.564197990323784, "tcpi": 0.527436974789916, "tracked_installs": 714, "name": "Alpha N1 C1", "icon_url": "", "app_id": "c53de2ed-14cb-46f9-82ba-f4da3ea36520", "app_name": "Alpha", "app_icon_url": "/default_app_icon.png", "ad_network_id": 900011, "ad_network_name": "Network One", "ad_network_icon_url": "", "platform": "ios", "bundle_id": "com.example.alpha", "store_id": "2000000001" } }, { "id": "2026-08-25,7ab8995e-0772-4171-8962-de739f98280f", "type": "report", "attributes": { "date": "2026-08-25", "campaign_id": "7ab8995e-0772-4171-8962-de739f98280f", "spend": 181.14000000000001, "impressions": 120110, "clicks": 2134, "installs": 805, "cpi": 0.2250186335403727, "ctr": 1.7767046873699108, "cvr": 37.722586691658854, "tcpi": 0.20490950226244345, "tracked_installs": 884, "name": "Alpha N1 C2", "icon_url": "", "app_id": "c53de2ed-14cb-46f9-82ba-f4da3ea36520", "app_name": "Alpha", "app_icon_url": "/default_app_icon.png", "ad_network_id": 900011, "ad_network_name": "Network One", "ad_network_icon_url": "", "platform": "ios", "bundle_id": "com.example.alpha", "store_id": "2000000001" } } ], "links": { "self": "https://api.tenjin.com/v2/reports/spend?start_date=2026-08-25&end_date=2026-08-31&group_by=campaign&granularity=daily&per_page=20&page=1", "last": "https://api.tenjin.com/v2/reports/spend?end_date=2026-08-31&granularity=daily&group_by=campaign&page=2&per_page=20&start_date=2026-08-25", "next": "https://api.tenjin.com/v2/reports/spend?end_date=2026-08-31&granularity=daily&group_by=campaign&page=2&per_page=20&start_date=2026-08-25" }, "meta": { "count": 35, "per_page": 20, "start_date": "2026-08-25", "end_date": "2026-08-31", "granularity": "daily", "metrics": [ "spend", "impressions", "clicks", "installs", "cpi", "ctr", "cvr", "tcpi", "tracked_installs" ], "organization_id": "ce301e87-e26a-4626-aa7e-c8f0501cd1af", "app_ids": [], "ad_network_ids": [], "group_by": "campaign_id", "countries": [], "campaign_ids": [], "platforms": [] } } ``` **Example: Group by channel,app,country, totals** ```json { "data": [ { "id": "900011,e31e4c10-667b-461a-8388-5a8ac6c77480,BR", "type": "report", "attributes": { "ad_network_id": 900011, "app_id": "e31e4c10-667b-461a-8388-5a8ac6c77480", "country": "BR", "spend": 764.77, "impressions": 258890, "clicks": 9554, "installs": 2474, "cpi": 0.30912287793047694, "ctr": 3.6903704275947313, "cvr": 25.894913125392506, "tcpi": 0.4107250268528464, "tracked_installs": 1862, "app_name": "Alpha", "app_icon_url": "/default_app_icon.png", "bundle_id": "com.example.alpha", "store_id": "2000000001", "platform": "ios", "ad_network_name": "Network One", "ad_network_icon_url": "" } }, { "id": "900012,e31e4c10-667b-461a-8388-5a8ac6c77480,BR", "type": "report", "attributes": { "ad_network_id": 900012, "app_id": "e31e4c10-667b-461a-8388-5a8ac6c77480", "country": "BR", "spend": 296.46, "impressions": 248003, "clicks": 2631, "installs": 986, "cpi": 0.3006693711967545, "ctr": 1.0608742636177788, "cvr": 37.47624477385025, "tcpi": 0.38854521625163824, "tracked_installs": 763, "app_name": "Alpha", "app_icon_url": "/default_app_icon.png", "bundle_id": "com.example.alpha", "store_id": "2000000001", "platform": "ios", "ad_network_name": "Network Two Account", "ad_network_icon_url": "" } } ], "links": { "self": "https://api.tenjin.com/v2/reports/spend?start_date=2026-08-25&end_date=2026-08-31&group_by=channel%2Capp%2Ccountry&granularity=totals-daily" }, "meta": { "count": 15, "per_page": 100, "start_date": "2026-08-25", "end_date": "2026-08-31", "granularity": "totals-daily", "metrics": [ "spend", "impressions", "clicks", "installs", "cpi", "ctr", "cvr", "tcpi", "tracked_installs" ], "organization_id": "fcb1ab2e-9dbb-453f-b5d9-9bb02a014533", "app_ids": [], "ad_network_ids": [], "group_by": "ad_network_app_country", "countries": [], "campaign_ids": [], "platforms": [] } } ``` ### 400, 401, 403, 498 - `400` A param is missing or invalid, a record is not found, or the request cannot be served - `401` Missing or invalid credentials, or no access to the requested data - `403` Invalid token, or the user's role does not allow the request - `498` Expired token, or a token with an invalid signature **Content type:** `application/json` schema: `Error` - **`error` (required)**: `string` What went wrong **Example:** ```json { "error": "" } ``` ### 429 More than 100 report requests in a minute with one access token **Headers:** - **`X-Retry-After`** Length of the rate limit period, in seconds `integer` **Content type:** `application/json` *Schema `Error` is shown above.* **Example:** ```json { "error": "" } ``` ## Schemas - `Error` — shown above. - `SpendReportDocument` — shown above. - `Links` — shown above. - `SpendReportMeta` — shown above. - `SpendReportResource` — shown above.