Skip to main content
GET
/
ad_reports
JavaScript
import Whop from '@whop/sdk';

const client = new Whop({
  apiKey: process.env['WHOP_API_KEY'], // This is the default and can be omitted
});

const adReport = await client.adReports.retrieve({
  from: '2023-12-01T05:00:00.401Z',
  to: '2023-12-01T05:00:00.401Z',
});

console.log(adReport.breakdown);
{
  "summary": {
    "clicks": 42,
    "impressions": 42,
    "reach": 42,
    "spend": 6.9,
    "click_through_rate": 6.9,
    "cost_per_click": 6.9,
    "cost_per_mille": 6.9,
    "frequency": 6.9,
    "result_count": 42,
    "result_label_override": "<string>",
    "cost_per_result": 6.9,
    "return_on_ad_spend": 6.9
  },
  "granularity": [
    {
      "bucket_start": "2023-12-01T05:00:00.401Z",
      "stat_date": "2023-12-01T05:00:00.401Z",
      "stat_hour": 42,
      "spend": 6.9,
      "impressions": 42,
      "clicks": 42,
      "reach": 42,
      "result_count": 42,
      "result_label_override": "<string>"
    }
  ],
  "breakdown": [
    {
      "id": "<string>",
      "name": "<string>",
      "summary": {
        "clicks": 42,
        "impressions": 42,
        "reach": 42,
        "spend": 6.9,
        "click_through_rate": 6.9,
        "cost_per_click": 6.9,
        "cost_per_mille": 6.9,
        "frequency": 6.9,
        "result_count": 42,
        "result_label_override": "<string>",
        "cost_per_result": 6.9,
        "return_on_ad_spend": 6.9
      },
      "granularity": [
        {
          "bucket_start": "2023-12-01T05:00:00.401Z",
          "stat_date": "2023-12-01T05:00:00.401Z",
          "stat_hour": 42,
          "spend": 6.9,
          "impressions": 42,
          "clicks": 42,
          "reach": 42,
          "result_count": 42,
          "result_label_override": "<string>"
        }
      ]
    }
  ]
}

Authorizations

​
Authorization
string
header
required

A company API key, company scoped JWT, app API key, or user OAuth token. You must prepend your key/token with the word 'Bearer', which will look like Bearer ***************************

Query Parameters

​
ad_campaign_ids
string[] | null

Scope the report to these ad campaigns (max 100); stats are summed across them. Mutually exclusive with companyId, adGroupIds, and adIds.

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

​
ad_group_ids
string[] | null

Scope the report to these ad groups (max 100); stats are summed across them. Mutually exclusive with companyId, adCampaignIds, and adIds.

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

​
ad_ids
string[] | null

Scope the report to these ads (max 100); stats are summed across them. Mutually exclusive with companyId, adCampaignIds, and adGroupIds.

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

​
breakdown
enum<string> | null

Entity level to break down the report by. When set, breakdown on the response contains one row per entity at the requested level inside the requested scope. ad returns one row per ad, ad_group per ad group, campaign per ad campaign. The breakdown level must be at or below the scope (e.g. adId cannot be broken down by campaign). The summary totals are unaffected.

Available options:
campaign,
ad_group,
ad
​
company_id
string | null

The unique identifier of a company. Mutually exclusive with adCampaignIds, adGroupIds, and adIds. Use with breakdown to fan out across every campaign, ad group, or ad in the company without paging.

Example:

"biz_xxxxxxxxxxxxxx"

​
currency
string | null

ISO 4217 currency code to report spend in. Defaults to the company's ads reporting currency.

​
from
string<date-time>
required

Inclusive start of the reporting window.

Example:

"2023-12-01T05:00:00.401Z"

​
granularity
enum<string> | null

Bucket grain for the per-bucket granularity time series. Omit (null) for summary-only. hourly/daily max 90 days, weekly max 366 days, monthly max 4 years. The summary totals are unaffected. With breakdown, each row gets its own series at the same grain.

Available options:
hourly,
daily,
weekly,
monthly
​
to
string<date-time>
required

Inclusive end of the reporting window.

Example:

"2023-12-01T05:00:00.401Z"

Response

A successful response

An ads performance report. Always returns a summary. The granularity field contains a per-bucket time series when the granularity arg is set; the breakdown field contains per-entity rows when the breakdown arg is set.

​
summary
object
required

Aggregate totals and rates over the date range.

​
granularity
object[] | null
required

Per-bucket time series over the date range, ordered ascending by bucketStart. null when the granularity arg on adReport is omitted; otherwise contains rows at the requested grain (daily or hourly).

​
breakdown
object[] | null
required

Per-entity rows over the date range. null when the breakdown arg on adReport is omitted; otherwise contains one row per ad campaign, ad group, or ad inside the requested scope at the requested level.