Log API

What is the MOLOCO Cloud Log API

MOLOCO Cloud Log API provides customers with a comprehensive set of APIs to create logs about every single impression, click, and conversion event of MOLOCO Cloud campaigns. The Moloco Cloud Log API is only available to limited customers depending on the contract.

• Create / Read / List / Delete logs. Conceptually, the ‘log’ object is a group of parameters that will be used to create log files. The parameters include ad account, log type, log file format, and date. The supported log types are 'IMP' for impressions, 'CLICK' for clicks, and 'CONVERSION' for conversion events. For log file formats, we support CSV and Avro. Date represents the date for which we extract the log data.
• Read log status. Whenever a new log object is created, a designated log generation job is also created. What the job does is to publish the log files to a location where a customer can retrieve them. By calling this API, you can check the status of the job and see where you can download the log files.

Usage example: Create a Log

Creating a log is as simple as providing aforementioned parameters, such as (1) ad account ID, (2) log type, (3) file format, and (4) date for the log.

$ cat log.json
{
  "ad_account_id": "$AD_ACCOUNT_ID",
  "type": "IMP",
  "format": "CSV",
  "date": "2020-03-20"
}
 
$ curl -X POST \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d "@log.json" https://api.moloco.cloud/cm/v1/logs?ad_account_id=$AD_ACCOUNT_ID
 
{
  "log": {
    "id": "$LOG_ID",
    "ad_account_id": "$AD_ACCOUNT_ID",
    "type": "IMP",
    "format": "CSV",
    "date": "2020-03-20",
    "created_at": "2020-03-25T08:33:04.893786Z",
    "updated_at": "2020-03-25T08:33:04.893786Z"
  },
  "href": "https://api.moloco.cloud/cm/v1/logs/$LOG_ID",
  "status": "https://api.moloco.cloud/cm/v1/logs/$LOG_ID/status"
}

In this example, your log parameters are in the log.json file and are delivered to the Log Creation API as an HTTP POST request body. You can find the available log types and log file formats from the API reference.

In the request response, you can find various information such as (1) the log ID ($LOG_ID), (2) the location where your log creation input is stored (href), and (3) the URL that you can check the status of the actual log generation job (status).

In most cases, what you want to do after calling the Log Creation API is to access the URI returned in the status field to see if the log creation job is complete.

About the $ID_TOKEN, please see the "Getting Started with MOLOCO Cloud API". In the "Prerequisite" section, you can find the information to create $ID_TOKEN for the MOLOCO Cloud API authentication.

Usage example: Access a Log

Accessing the log is as simple as calling the URI endpoint returned in status field in the body of the Log Creation API call result.

$ curl \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
https://api.moloco.cloud/cm/v1/logs/$LOG_ID/status
 
{
  "status": "READY",
  "location_csv": [ 
    "https://$LOG_STORAGE/$DATE/$WORKPLACE_$AD_ACCOUNT_ID_$TYPE_$DATE_$LOG_ID-000000000000.csv.gz?Expires=$TIMESTAMP&GoogleAccessId=$GOOGLE_ACCESS_ID&Signature=$SIGNATURE"
  ]
}

In the above example response body, you can find the log file format is CSV, which is the format that you specified when you create the log object. The location_csv is actually a json array because it can be multiple files if the volume of logs is too large to store in one file.

Once the value of the field status is changed into READY as in the example, you can download the log files from the locations in location_csv.

The value or format of $LOG_STORAGE is subject to change, thus you shouldn't write any logics depending on the value.