Retrieve ad report

Performance report for a company, ad campaign, ad group, or ad. Always returns aggregate summary totals. Set granularity (daily/hourly) to additionally get a time series, or set breakdown (campaign/ad_group/ad) to additionally get per-entity rows inside the requested scope. Exactly one of companyId, adCampaignId, adGroupId, or adId must be provided.

Required permissions:

• ad_campaign:stats:read

GET /ad_reports

JavaScript

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);

200

{
  "summary": {
    "clicks": 42,
    "impressions": 42,
    "reach": 42,
    "spend": 6.9,
    "ctr": 6.9,
    "cpc": 6.9,
    "cpm": 6.9,
    "frequency": 6.9,
    "result_count": 42,
    "result_label_override": "<string>",
    "cost_per_result": 6.9,
    "roas": 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,
        "ctr": 6.9,
        "cpc": 6.9,
        "cpm": 6.9,
        "frequency": 6.9,
        "result_count": 42,
        "result_label_override": "<string>",
        "cost_per_result": 6.9,
        "roas": 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_id · string | null

The unique identifier of an ad campaign. Mutually exclusive with companyId, adGroupId, and adId.

ad_group_id · string | null

The unique identifier of an ad group. Mutually exclusive with companyId, adCampaignId, and adId.

ad_id · string | null

The unique identifier of an ad. Mutually exclusive with companyId, adCampaignId, and adGroupId.

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 adCampaignId, adGroupId, and adId. 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 time series returned in granularity on the response. Omit (null) for summary-only. daily returns one row per day; hourly returns up to 24 rows per day (zero-activity hours are omitted). The summary totals are unaffected. Combined with breakdown, each breakdown row also gets its own per-bucket time series at the same grain.

Available options: daily, hourly

to · string<date-time> · required

Inclusive end of the reporting window.

Example:

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

Response

200

application/json

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.

Show child attributes

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).

Show child attributes

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.

Show child attributes