General information

We're thrilled to introduce our reporting API.
If you're interested in accessing our reporting API, please don't hesitate to reach out to us.

Authentication

All API requests require an API token - this key should have been provided to you by an Account Manager at Vibe. You can provide the token under an X-API-KEY HTTP header.

Rate Limits

There is no rate limiting implemented at the moment but Vibe reserves the right to adjust the rate limit for given endpoints to continue and provide a high quality of service to all of our customers.

Limitations

Vibe is updating the data every hour. The figures might evolve slightly as it is still partial data, because of the CTV environment, until six or seven hours post-impression.
We suggest fetching at least 1 day of past data, and also erasing the last day of data when requesting API reports.

List of Reporting API Endpoints

For the current version of the API (v1), only async reporting endpoints are available.

Name	Method	URL	Description
Create Async Report	POST	https://clear-platform.vibe.co/rest/reporting/v1/create_async_report	Return a report_id for a specifically asked report (dimensions, metrics, filters etc.). This report_id is then used to fetch the report download URL from the Get Report Status endpoint.
Get Report Status	GET	https://clear-platform.vibe.co/rest/reporting/v1/get_report_status	Returns the status of a given report - and if ready a download URL.
Get Advertiser IDs	GET	https://clear-platform.vibe.co/rest/reporting/v1/get_advertiser_ids	Returns the list of advertiser ID and their associated name.
Get Advertiser App IDs	GET	https://clear-platform.vibe.co/rest/reporting/v1/get_app_ids	Return the app ID list of a given advertiser.

Create Async Report Endpoint

POST	https://clear-platform.vibe.co/rest/reporting/v1/create_async_report

Usage

This is the main endpoint for getting reporting data from Vibe. The endpoint generates an asynchronous report query based on the reporting dimensions, metrics, filters, and other details that you specify, and returns the Report ID. The next step is to query the ”Get Report Status” endpoint to see when the report is done and to get a download URL.

Parameters

Authentification

HTTP Header	Format	Description	Mandatory
X-API-KEY	String	API key to use as an authentification measure to the API.	Y

Basic parameters

Parameter	Format	Description	Mandatory	Example
start_date	Date (YYYY-MM-DD)	Minimum date for which to return data. Should be between 45 days ago and the current date.	Y	2024-01-13
end_date	Date (YYYY-MM-DD)	Maximum date for which to return data. Should be between 45 days ago and the current date (included).	Y	2024-01-20
timezone	String (Timezone Identifier*)	Timezone of the returned data. The supported timezone list is available at the end of the documentation.	N (UTC by default)	America/New_York
advertiser_id	String OR List of String (UUID)	The advertiser id(s) for which you are requesting the data. Should be owned by the tenant requesting the API key. It is available on the vibe.co platform. Click on the “Edit advertiser” button of your advertiser, under the Advertisers page. You can also use the Get Advertiser IDs Endpoint if you have multiple advertiser IDs which you want to pull data from.	Y	e3f628ee-35a4-4895-80f1-d4f8a56986ad OR [e3f628ee-35a4-4895-80f1-d4f8a56986ad,f4g739ee-35a4-4895-80f1-d4f8a57098bd]

Field selection parameters

Parameter	Format	Description	Mandatory	Example
dimensions	String	A JSON list of dimensions. See Metrics, Dimensions, and Filters for more information about each dimension. If not sent in the payload, only the metrics per date will be returned in the report.	N	["advertiser_id", "advertiser_name", "channel_name"]
metrics	String	A JSON list of metrics. See Metrics, Dimensions, and Filters for more information about each dimension. At least one metric must be in the list.	Y	["spend","impressions"]
attribution_window	String	The desired attribution window for web-pixel metrics. Will affect web-pixel metrics only. Possible values: "1h", "6h", "12h", "24h", "48h", "72h", "7 days", "30 days"	N (7 days by default)	"30 days"
granularity	String	The desired time aggregation granularity. Possible values: "hour", "day", "week", "month"	N (day by default)	"week"

Filtering parameters

Parameter	Format	Description	Mandatory	Example
filters	JSON	A JSON list of filter objects where each contains a dimension and value(s). Use this parameter to apply more advanced filtering. Note that if you specify more than one filter they will be applied with an AND relation. See Metrics, Dimensions, and Filters for more information about each filter.	N	'[{"dimension": "campaign_id", "values": ["2b54b588-19a9-4424-a368-b30df9fea6ae"]}, {"dimension": "strategy_id", "values": ["763c5d2b-68eb-4ddd-9c34-ad6025c24ffb", "981a05f4-7203-4c23-8eeb-5c8a3047792b"]}]'

Formatting parameters

Parameter	Format	Description	Mandatory	Example
format	String	The format in which the query results will be delivered. Options: "JSON" (default) or "CSV" (comma used as separator).	Y	CSV

Metrics, Dimensions, and Filters

Metrics

Name	Format	Description
spend	Float	Ad-spend amount in US dollars.
impressions	Float	Number of impressions. Float and not an Integer, because impressions can be split among multiple app IDs, (MMP-only).
households	Float	Number of unique households reached.
cpm	Float	Cost per mille impressions in USD.
completed_views	Float	Number of completed views (100%).
cost_per_completed_view	Float	Cost per completed views in USD.
view_through_rate	Float	Completed views divided by impressions (value returned in percentage format).
page_views	Float	Number of page views attributed to Vibe. Web-based metric only.
cost_per_page_view	Float	Cost per page view in USD.
number_of_sessions	Float	Number of sessions attributed to Vibe. Web-based metric only.
cost_per_session	Float	Cost per session in USD.
number_of_leads	Float	Number of leads attributed to Vibe. Web-based metric only.
cost_per_lead	Float	Cost per lead in USD.
installs	Float	Number of app installs attributed to Vibe.
cost_per_install	Float	Cost per app install in USD.
number_of_purchases	Float	Number of in-app purchases attributed to Vibe if you are using an MMP or number of web purchases attributed to Vibe if you are using a Vibe pixel.
cost_per_purchase	Float	Cost per purchase in USD.
amount_of_purchases	Float	Amount of in-app purchases attributed to Vibe in US dollars.
number_of_signups	Float	Number of in-app signups attributed to Vibe if you are using an MMP.
cost_per_signup	Float	Cost per signup in USD
number_of_custom_1	Float	Number of custom 1 events attributed to Vibe if you are using an MMP.
cost_per_custom_1	Float	Cost per custom 1 in USD
number_of_custom_2	Float	Number of custom 2 events attributed to Vibe if you are using an MMP.
cost_per_custom_2	Float	Cost per custom 2 in USD
number_of_custom_3	Float	Number of custom 3 events attributed to Vibe if you are using an MMP.
cost_per_custom_3	Float	Cost per custom 3 in USD
roas	Float	Return on ad Spend (value returned in percentage format).

Dimensions

Name	Format	Description
impression_date	String (YYYY-MM-DD)	Date of the impression in the requested timezone. The default timezone is UTC. Note that this dimension is always returned and thus does not need to be specified in the “dimensions” list in the payload.
advertiser_id	String (UUID)	UUID represents the Advertiser ID in the Vibe platform.
advertiser_name	String	Advertiser Name in the Vibe platform.
campaign_id	String (UUID)	UUID represents the Campaign ID in the Vibe platform.
campaign_name	String	Campaign Name in the Vibe platform.
strategy_id	String (UUID)	UUID represents the Strategy ID in the Vibe platform.
strategy_name	String	Strategy Name in the Vibe platform.
creative_id	String (UUID)	UUID represents the Creative ID in the Vibe platform.
creative_name	String	Creative Name in the Vibe platform.
app_id	String	Android or iOS App ID. Note that when specified, if you have multiple app IDs, the impressions and ad spend will be split evenly between app IDs.
os	String	Os of the app_id (Android or IOS). Web if the data you are pulling is based on web-pixel activity.
screen	String	Screen on which the impression occurred (TV, Mobile, Tablet)
channel_name	String	The channel name on which the impression occurred (Pluto, ESPN, Tubi, etc.)
geo_region	String	The region (US state), in which the impression occurred.
geo_metro	String	The metro (DMA), in which the impression occurred.
geo_city	String	The city in which the impression occurred.
geo_zip	String	The zip code in which the impression occurred.
segment_ages	String	The age audience on which the impression occurred.
segment_career	String	The career audience on which the impression occurred.
segment_education	String	The education audience on which the impression occurred.
segment_estimated_incomes	String	The estimated income audience on which the impression occurred.
segment_estimated_net_worth	String	The estimated net worth audience on which the impression occurred.
segment_ethnicity	String	The ethnicity audience on which the impression occurred.
segment_family_composition	String	The family composition audience on which the impression occurred.
segment_genders	String	The gender audience on which the impression occurred.
segment_interests	String	The interest audience on which the impression occurred.
segment_languages	String	The language audience on which the impression occurred.
segment_political_status	String	The political audience on which the impression occurred.
segment_retargeting	String	The retargeting audience on which the impression occurred. Only for retargeting campaigns.

Filters

Name	Format	Description
app_id	String	In the App environment, app_id of the apps on which the in-app events are tracked (iOS or Android). For instance com.xyz.abc (Android), id1234567 (IOS). Note that iOS app_ids always need to be prefixed by “id”. In the Web environment, app_id is linked to the pixel used for tracking web activity for a given advertiser. For instance Ks2bwm.
campaign_id	String (UUID)	UUID represents the Campaign ID in the Vibe platform.
strategy_id	String (UUID)	UUID represents the Strategy ID in the Vibe platform.

Output

Name	Format	Description
report_id	String (UUID)	The report ID corresponds to your payload.

Sample query and output

Query snippet (Python)

import requests

# Values to set for a quick test
ADVERTISER_ID = "<ADVERTISER_ID>"
START_DATE = "2024-08-01"
END_DATE = "2024-08-02"
APP_IDS = ["<APP_ID_1>", "<APP_ID_2>"]

X_API_KEY = "<API_KEY>"

# Payload and headers
payload = {
    "advertiser_id": ADVERTISER_ID,
    "metrics": [
        "spend",
        "impressions",
        "installs",
        "number_of_purchases",
        "amount_of_purchases"
    ],
    "dimensions": ["campaign_name", "app_id"],
    "start_date": START_DATE,
    "end_date": END_DATE,
    "timezone": TIMEZONE,
    "format": "csv",
    "filters": [
        {
            "dimension": "app_id",
            "values": APP_IDS,
        },
    ],
}

headers = {'X-API-KEY': X_API_KEY}

# Generate async report
create_response = requests.post(
    "https://clear-platform.vibe.co/rest/reporting/v1/create_async_report", json=payload, headers=headers
)

response_data = create_response.json()
print(f"{response_data}")

Output

{"report_id": "946fcf93-0a58-4dee-9534-88ff133b8ec8"}

Get Report Status Endpoint

POST	https://clear-platform.vibe.co/rest/reporting/v1/get_report_status

Usage

This endpoint returns the status of a given report that was generated using the “Create Async Report” endpoint. If the report has finished running, the endpoint also returns a download URL.

Important:

Reports can sometimes take up to a few minutes to complete.
Do not query the Get Report endpoint more than once every 10 seconds per report.
Set a timeout. In some rare cases, a report can get stuck in "created" or "processing" status. If the status is not "done" or "error" after 30 minutes, we recommend submitting the report again (which will give you a new report ID to query).
When ready, a report is available through a URL only for 24 hours.

Query parameters

Authentification

HTTP Header	Format	Description	Mandatory	Example
X-API-KEY	String	API key to use as an authentification measure to the API.	Y

Basic parameters

Name	Format	Description	Mandatory
report_id	String (UUID)	A Report ID is returned by the Create Async Report endpoint.	Y

Output

Name	Format	Description	Example value
report_id	String (UUID)	The report ID for which you asked the status.	946fce93-0a58-4dee-9534-88ff133b8ec8
status	String	The status of the report: - *created: the report has just been created, we cannot access the report yet. - processing: The API is processing the report, we cannot access the report yet. - error: an error has occurred during the report creation - no report will be available. - done*: the report is processed and can be accessed (see download_url).	done
generated_url_time	String	Generation time of the URL to download the report.	2024-01-01T08:26:18.457690+00:00
url_expiration_time	String	Expiration time of the URL to download the report.	2024-01-30T08:26:18.457690+00:00
download_url	String	The download URL of the report.	https://xxx.amazonaws.com/xxxxxxxxx

Sample query and output

Query snippet (Python)

import uuid
import time
import requests

# Values to set for a quick test
REPORT_UUID = "<REPORT_UUID>"
X_API_KEY = "<API_KEY>"


# Check if report is ready
headers = {'X-API-KEY': X_API_KEY}

while True:
    get_status_response = requests.get(
        f"https://clear-platform.vibe.co/rest/reporting/v1/get_report_status?report_id={uuid.UUID(REPORT_UUID)}",
        headers=headers
    ).json()

    if (
            "status" in get_status_response
            and get_status_response["status"] != "CREATED" and get_status_response["status"] != "PROCESSING"
    ):
        print(f'{REPORT_UUID} : {get_status_response}')
        break
    
    time.sleep(10)
    print('Sleeping 10 seconds as report is not ready yet')

Output

{
     "status": "done",
     "generated_url_time": "2024-01-01T08:26:18.457690+00:00",
     "url_expiration_time": "2024-01-30T08:26:18.457690+00:00",
     "download_url": "https://xxx.amazonaws.com/xxxxxxxxx",
     "report_id": "946fce93-0a58-4dee-9534-88ff133b8ec8"
 }

Get Advertiser IDs Endpoint

GET	https://clear-platform.vibe.co/rest/reporting/v1/get_advertiser_ids

Usage

This endpoint returns all the advertiser IDs and their associated advertiser names.

Query Parameters

HTTP Header	Format	Description	Mandatory	Example
X-API-KEY	String	API key to use as an authentification measure to the API.	Y

Output

[ 
   { 
      "advertiser_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "advertiser_name": "Advertiser"
   } 
]

Get Advertiser App IDs Endpoint

GET	https://clear-platform.vibe.co/rest/reporting/v1/get_app_ids

Usage

This endpoint returns all the app ID values available for a given advertiser.

Query parameters

HTTP Header	Format	Description	Mandatory	Example
X-API-KEY	String	API key to use as an authentification measure to the API.	Y

Basic parameters

Name	Format	Description	Mandatory
advertiser_id	String (UUID)	Advertiser on which you want to return the list of App IDs.	Y

Output

Name	Format	Description	Example value
app_ids	List[String]	List of App IDs.	["com.xyz.abc","id1234567"]

Error Codes

Vibe uses standard HTTP response codes to indicate the success or failure of an API request. In general, 200 codes correspond to success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx codes are for other issues.

Code	Information
400	General error code, please check the error message for additional context. For instance, provided start_date could be more recent than the end_date.
403	The request is denied access. It can happen for instance if you try to access an advertiser ID data which does not belong to the tenant owning the API key you are using.
422	The query parameters or payload do not match the expected format. Please check the error message for additional context.
500	The request has failed due to an internal error. Typically, this just means you should retry your API call.