Skip to main content

Run a Synchronous Report

  • Updated

Use this endpoint to run a synchronous report task.

Request

End Point https://business.newsbreak.com/business-api/v1/reports/getIntegratedReport

Method POST

Header

Field Required Data Type Description
Access-Token Y string Authorized access token. 
Content-Type Y string Request message type
Allowed format:application/json

Request Parameters (case-sensitive)

Field Required Data Type Description
name Y string Name of this report.
timezone Y string Valid string representing timezone, such as UTC, America/Los_Angeles, Asia/Shanghai, etc. The default timezone is PDT.
dateRange Y enumerate FIXED, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, MONTH_TO_DATE, QUARTER_TO_DATE, TODAY.
startDate N string Start date of the report. It's required when dateRange=FIXED.
Date should be formatted as "YYYY-mm-dd" like "2024-01-01".
endDate N string End date of the report. It's required when dateRange=FIXED.
Date should be formatted as "YYYY-mm-dd" like "2024-01-01".
filter N enumerate Filter type. ORG,AD_ACCOUNT,CAMPAIGN,AD_SET,AD.
dataSource N enumerate Data source type. HOURLY,REALTIME.
Default as HOURLY.
Hourly report is the official basis for income settlement on NewsBreak.
filterIds N list of int IDs of filter.
dimensions Y list of string

Dimensions. Available dimensions (UPPERCASE only): DATE,HOUR,ORG,AD_ACCOUNT,CAMPAIGN,AD_SET,AD,PLACEMENT. 

Date range restrictions apply:
• HOUR dimension: Only works with dateRange of YESTERDAY, TODAY, or FIXED with 1-day duration maximum.
• DATE dimension: Works with YESTERDAY, TODAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, MONTH_TO_DATE, or FIXED with 30-day duration maximum.
metrics Y list of string Available metrics (UPPERCASE only): COST, IMPRESSION, CLICK, CONVERSION, VALUE,CPM, CPC, CPA, CTR, CVR, VPA, COMPLETE_PAYMENT_ROAS, SALE_ROAS, APP_PURCHASE_ROAS, APP_IN_APP_AD_IMPR_ROAS.
eventMetrics N list of object

Each object requires eventType and metrics. 

eventType is a string, represents the Event Type that you want to see report data of, eg. add_to_cart, complete_payment, app_install, app_purchase, app_in_app_ad_impr etc.. eventType names must be in LOWERCASE.

metrics is a list of string, represents the metrics of each eventType that you want to see report data of, COUNT, VALUE, CPA, VPA, CVR. metric names must be in UPPERCASE.

Example

curl --location --request POST 'https://business.newsbreak.com/business-api/v1/reports/getIntegratedReport' \
  -H 'Content-Type: application/json' \
  -H 'Access-Token:{{Access-Token}}' \
  -d '{
  "name": "my report example",
  "timezone": "Asia/Shanghai",
  "dateRange": "FIXED",
  "startDate": "2024-01-01",
  "endDate": "2024-01-01",
  "filter": "AD_SET",
  "dataSource": "REALTIME",
  "filterIds": [
    123456789
  ],
  "dimensions": [
    "DATE","AD_SET","AD","AD_ACCOUNT","CAMPAIGN"
  ],
  "metrics": [
    "COST","IMPRESSION"
  ],
  "eventMetrics":[
    {"eventType":"complete_payment","metrics":["COUNT","VALUE","CPA","VPA","CVR"]},
    {"eventType":"app_in_app_ad_impr","metrics":["COUNT","VALUE","CPA","VPA","CVR"]}
]
}'
 

Response

Response Parameters

Field Data Type Description
code int Status code, see Return Codes.
errMsg string Error message when code!=0.
data object Response object.
└── rows object[] List of reports returned.
    └── date string Date.
    └── hour string Hour.
    └── adAccountId string Ad account ID.
    └── adAccount string Ad account name.
    └── orgId string Organization ID.
    └── organization string Organization name.
    └── campaignId string Campaign ID.
    └── campaign string Campaign name.
    └── adSetId string Ad set ID.
    └── adSet string Ad set name.
    └── adId string Ad ID.
    └── ad string Ad name.
    └── placement string Placement name
    └── costDecimal double Cost in cents. 
    └── cost int Cost in cents. 
    └── impression int Impression.
    └── click int Click.
    └── conversion int Conversion.
    └── conversionValueDecimal double Total conversion value in cents.
    └── conversionValue int Total conversion value in cents.
    └── cpmDecimal double CPM in cents, -1.0 if N/A.
    └── cpm int CPM in cents, -1 if N/A.
    └── cpcDecimal double CPC in cents, -1.0 if N/A.
    └── cpc int CPC in cents, -1 if N/A.
    └── cpaDecimal double Cost per action in cents, -1.0 if N/A.
    └── cpa int Cost per action in cents, -1 if N/A.
    └── ctr int CTR * 10000 in basis points, -1 if N/A.
    └── cvr int CVR * 10000 in basis points, -1 if N/A.
    └── vpaDecimal double Value per action in cents, -1.0 if N/A.
    └── vpa int Value per action in cents, -1 if N/A.
    └── eventCount object Event type and the total count of each event.
    └── eventValueDecimal object Event type and the total value of each event in double.
    └── eventValue object Event type and the total value of each event in int.
    └── eventCpaDecimal object Event type and CPA of each event in double.
    └── eventCpa object Event type and CPA of each event in int.
    └── eventVpaDecimal object Event type and VPA of each event in double.
    └── eventVpa object Event type and VPA of each event in int.
    └── eventCvr object Event type and CVR of each event. No eventCvr for app campaigns. 
    └── roas double Return on ad spend, -1.0 if N/A.
    └── completePaymentRoas double Complete payment return on ad spend, -1.0 if N/A.
    └── saleRoas double Sale return on ad spend, -1.0 if N/A.
    └── appPurchaseRoas double App purchase return on ad spend, -1.0 if N/A.
    └── appInAppAdImprRoas double App in app ad impression return on ad spend, -1.0 if N/A.
└── aggregateData object[] Aggregated summary data calculated from all report rows. Each object contains the total metrics over the queried period.

Example

{
    "code": 0,
    "data": {
        "rows": [
            {
                "date": "2023-10-20",
                "adId": "123456789",
                "ad": "example report",
                "adSetId": "123456789",
                "adSet": "example ad set",
                "campaignId": "123456789",
                "campaign": "example campaign",
                "adAccountId": "123456789",
                "adAccount": "example ad account",
                "cost": 122715,
                "costDecimal": 122715.0,
                "impression": 67260,
                "click": 1667,
                "conversion": 311708,
                "conversionValue": 220157,
                "conversionValueDecimal": 220157.0,
                "eventCount": {
                    "app_in_app_ad_impr": 312912
                },
                "eventValue": {
                    "app_in_app_ad_impr": 220263
                },
                "eventValueDecimal": {
                    "app_in_app_ad_impr": 220263.0
                },
                "eventCpa": {
                    "app_in_app_ad_impr": 654
                },
                "eventCpaDecimal": {
                    "app_in_app_ad_impr": 654.0
                },
                "eventVpa": {
                    "app_in_app_ad_impr": 274
                },
                "eventVpaDecimal": {
                    "app_in_app_ad_impr": 274.0
                },
                "eventCvr": {},
                "roas": 1.7940512569775495,
                "completePaymentRoas": 0.4194997370979588,
                "saleRoas": -1.0,
                "appPurchaseRoas": 0.0,
                "appInAppAdImprRoas": 0.0,
                "vpa": 32,
                "vpaDecimal": 32.0,
                "cpm": 1824,
                "cpmDecimal": 1824.0,
                "cpc": 73,
                "cpcDecimal": 73.0,
                "ctr": 248,
                "cpa": 60,
                "cpaDecimal": 60.0,
                "cvr": 1869874
            }
        ],
        "aggregateData": [
            {
                "cost": 122715,
                "costDecimal": 122715.0,
                "impression": 67260,
                "click": 1667,
                "conversion": 311708,
                "conversionValue": 220157,
                "conversionValueDecimal": 220157.0,
                "eventCount": {
                    "app_in_app_ad_impr": 312912
                },
                "eventValue": {
                    "app_in_app_ad_impr": 220263
                },
                "eventValueDecimal": {
                    "app_in_app_ad_impr": 220263.0
                },
                "eventCpa": {
                    "app_in_app_ad_impr": 654
                },
                "eventCpaDecimal": {
                    "app_in_app_ad_impr": 654.0
                },
                "eventVpa": {
                    "app_in_app_ad_impr": 274
                },
                "eventVpaDecimal": {
                    "app_in_app_ad_impr": 274.0
                },
                "eventCvr": {},
                "completePaymentRoas": 0.4194997370979588,
                "saleRoas": -1.0,
                "appPurchaseRoas": 0.0,
                "appInAppAdImprRoas": 0.0,
                "vpa": 32,
                "vpaDecimal": 32.0,
                "cpm": 1824,
                "cpmDecimal": 1824.0,
                "cpc": 73,
                "cpcDecimal": 73.0,
                "ctr": 248,
                "cpa": 60,
                "cpaDecimal": 60.0,
                "cvr": 1869874
            }
        ]
    }
}
 

Related articles