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.

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

Limitations

When integrating with our API for daily or weekly data pulls we generally recommend splitting multi-day queries to single-day and iterating over the entire period.
The time aggregation is done by day only (in UTC by default)
We do support events coming from Singular MMP since 2024-02-13

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.	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"]

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).
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, 7d attribution-window 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, 7d attribution-window only.
cost_per_session	Float	Cost per session in USD.
number_of_leads	Float	Number of leads attributed to Vibe. Web-based metric, 7d attribution-window only.
cost_per_lead	Float	Cost per lead in USD.
installs	Integer	Number of app installs attributed to Vibe.
cost_per_install	Float	Cost per app install in USD.
number_of_purchases	Integer	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 (7d attribution-window only).
cost_per_purchase	Float	Cost per purchase in USD.
amount_of_purchases	Float	Amount of in-app purchases attributed to Vibe in US dollars.
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.
channel_name	String	The channel name on which the impression occurred (Pluto, ESPN, Tubi, etc.)

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-02-01"
END_DATE = "2024-02-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.