Moloco data integration solution

Last updated 10/05/2026

Last updated: 2022-05-18

1. Integration plan overview

tip

Note that data generated by third-party data integration counts toward the cluster's data consumption

Summary

This document describes how to send Moloco data back to Agentic Engine (hereinafter the AE system). This solution supports:

• Sending back aggregated metric data through the Moloco Report API, including impression, click, install, revenue, and cost metrics
• Sending back user-level raw data through the Moloco Log API, covering impression, click, and conversion data

Before you start connecting Moloco data, make sure you have read the AE system data rules and understand AE's data structure. We also recommend that you give the information needed to pull data to our customer success manager, using the format in the data integration configuration template.

Process

The Moloco data integration process is as follows:

1. Log in to your Moloco account and get the Workplace ID

2. Provide ThinkingAI staff with the Moloco account, password, and Workplace ID used for API calls

3. Determine how to pull data:

   1. Sending back aggregated metric data through the Moloco Report API
   2. Sending back user-level raw data through the Moloco Log API

4. Determine the data dimensions, metric types, pull frequency, and time range to pull

5. ThinkingAI staff complete the data pull development

6. Build dashboards and reports in the AE backend, and complete data validation

2. Preparation before integration

2.1 Get the Workplace ID

Before calling the API, you need to get the Workplace ID. Log in to your Moloco account and click the Settings button in the left sidebar to open the settings page. On the settings page, you can get the Workplace ID on the Information tab, as shown in the image below.

Figure 1. How to get the Workplace ID

2.2 Provide the Moloco account, password, and Workplace ID

Calling the Moloco API requires a Token, and generating the Token requires your Moloco account and password as well as the Workplace ID you got in the previous step.

Because a Token is valid for only one hour, you need to provide ThinkingAI staff with your Moloco account, password, and Workplace ID so that the system can generate a new Token each time it pulls data. We strictly follow confidentiality principles to prevent this information from leaking. For details about how Tokens are generated, see Moloco's official documentation.

You can also create a new Moloco account dedicated to API calls. See the image below for how to create a new account. You can also see this document for more information about creating a new account.

Figure 2. Creating a new user

3. Data pull

Moloco provides two ways to pull data: Report API, which sends back aggregated metric data, and Log API, which sends back user-level raw data.

3.1 Report API

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Report API	Pull	No	Aggregated data		Yes	Yes	Yes	Yes	Yes

Report API is an aggregated data API that returns metric data for a given time range. For details, see the official Report API documentation

3.1.1 Included metrics

Report API data contains the following five metric fields:

• impressions: number of impressions
• clicks: number of clicks
• installs: number of installs
• spend: user acquisition cost
• revenue: monetization revenue

3.1.2 API parameters

• Ad account:

  • When Report API pulls data, you need to specify the ad accounts to pull data from. We will try to pull data from all ad accounts. If you need to specify a list of ad accounts to pull, note it in the data integration configuration template

• Time:

  • Data can be pulled by day in UTC time

• Optional dimensions:

  • Moloco Report API provides the following analysis dimensions. By default, we select all dimensions to get the most fine-grained data:

    • DATE
    • APP_OR_SITE
    • CAMPAIGN
    • CREATIVE_GROUP
    • CREATIVE
    • EXCHANGE
    • SUB_PUBLISHER
    • TRAFFIC

3.1.3 Ingested data structure

• Because Report API returns aggregated data, we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
• The date field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
• The event name for Report API data is: moloco_report
• The following are the ingested fields of Report API:

------------------------Dimension fields------------------------
ad_account_currency
ad_account_id
ad_account_title
ad_group_id
ad_group_title
app_id
app_os
app_store_id
app_title
campaign_country
campaign_id
campaign_title
creative_id
creative_main_asset_location
creative_title
creative_type
creative_group_id
creative_group_title
exchange_id
site_domain
site_id
site_title
skan_conversion_value
skan_metric_conversion_count
sub_publisher_id
sub_publisher_title
traffic_is_lat
traffic_mmp_effective
traffic_skan_bid
------------------------Metric fields (numeric type)------------------------
clicks
impressions
installs
revenue
spend

3.2 Log API

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Log API	Pull	No	User level	Yes	Yes	Yes	Yes	Yes	Yes

Log API provides user-level raw data with very rich user information. It mainly provides three types of detailed data:

• IMP: impression data, which includes impressions and impression cost
• CLICK: click data, which includes clicks as well as the user's earlier impressions and impression cost
• CONVERSION: conversion data, which includes conversion, attribution, cost, and revenue data obtained from the MMP, as well as the user's earlier impressions and clicks

warning

Because the detailed data of Log API identifies specific users by ADID (that is, GAID) and IDFA, if you want to associate Moloco detailed data with AE users, you need to record ADID and IDFA in AE user properties, or set ADID and IDFA as the #distinct_id of AE users. Otherwise, the detailed data can't be associated with other AE user data.

3.2.1 API parameters

• Ad account:
  • When Log API pulls data, you need to specify the ad accounts to pull data from. We will try to pull data from all ad accounts. If you need to specify a list of ad accounts to pull, note it in the data integration configuration template
• Time:
  • Data for the previous day (UTC) can be pulled at 3AM - 4AM (UTC) every day

3.2.2 Ingested data structure

• For the specific returned fields of the three types of detailed data and their meanings, see the Moloco official documentation: https://help.moloco.com/hc/en-us/articles/360047856254-Log-data-field-specification
• We use req_device_ifa in the returned data as the ID that identifies the user. Make sure to set ADID and IDFA as the #distinct_id of AE users or in AE user properties
• The following fields are common to all three types of detailed data:

req_exchange
req_timestamp
req_app_bundle
req_app_publisher_id
req_device_ifa
req_device_os
req_device_osv
req_device_carrier
req_device_connectiontype
req_device_hwv
req_device_make
req_device_model
req_device_devicetype
req_device_language
req_device_ip
req_device_lmt
req_device_geo_country
req_device_geo_utcoffset
req_device_geo_region
req_device_geo_metro
req_device_geo_city
req_device_geo_zip
req_imp_bidfloor
req_imp_tagid
req_imp_banner_w
req_imp_banner_h
req_imp_video_maxduration
req_imp_video_minduration
req_imp_video_w
req_imp_video_h
req_imp_video_skip
req_imp_video_ext_is_rewarded
req_imp_native_ext_has_image
req_imp_native_ext_has_video
req_imp_instl
bid_mtid
bid_adaccount_id
bid_adaccount_title
bid_app_id
bid_app_title
bid_app_store_id
bid_campaign_id
bid_campaign_title
bid_adgroup_id
bid_adgroup_title
bid_creativegroup_id
bid_creativegroup_title
bid_creative_id
bid_creative_title
bid_creative_type
bid_creative_w
bid_creative_h
bid_creative_size_in_bytes
bid_creative_video_duration
bid_user_bucket
bid_adslot_type
bid_adslot_w
bid_adslot_h
bid_traffic_skan

IMP data (Impression)

The following fields are specific to IMP data:

• imp_timestamp, that is, the time when the impression occurred, is set as the #event_time of the record
• The event name for IMP data is: moloco_log_imp
• The unique fields are as follows:

imp_timestamp
imp_cost_moloco_micro
imp_cost_currency
imp_cost_fee_percent
imp_cost_total_micro
imp_ip

CLICK data

The following fields are specific to CLICK data:

• click_timestamp, that is, the time when the click occurred, is set as the #event_time of the record
• The event name for CLICK data is: moloco_log_click
• The unique fields are as follows:

click_timestamp
click_type
click_ip

CONVERSION data

The following fields are specific to CONVERSION data:

• cv_attribution_timestamp, that is, the time when attribution occurred, is set as the #event_time of the record
• The event name for CONVERSION data is: moloco_log_conversion
• The unique fields are as follows:

cv_mmp
cv_event
cv_timestamp
cv_attribution_timestamp
cv_attribution_is_view_through
cv_revenue_amount
cv_revenue_currency
cv_revenue_amount_usd
cv_postback

3.2.3 User property handling

Currently, we don't yet set fields in Moloco Log API detailed data as user properties. If you need to write some fields to user properties, specify them in the data integration configuration template.

4. Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI. We will pull the Moloco data based on this template:

Data interface: Moloco API
---------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
Moloco account name: XXX
Moloco account password: XXX
Moloco Workplace ID：XXX
Advertiser ID (ad_account_id) list: XXX, XXX
---------
Report API configuration
Time range: yyyy/mm/dd - yyyy/mm/dd
Grouping dimensions: DATE, APP_OR_SITE, CAMPAIGN, CREATIVE_GROUP, CREATIVE, EXCHANGE, SUB_PUBLISHER, TRAFFIC
---------
Log API configuration
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Event types: IMP, CLICK, CONVERSION
Fields to set as user properties: XXX

5. Integration testing and data usage

Integration testing

On the Management > Events page or the SQL IDE page in the AE system backend, search for the following events to check whether they have been ingested:

• Events for Report API:

  • moloco_report

• Events for Log API:

  • moloco_log_imp
  • moloco_log_click
  • moloco_log_conversion