Keep track of campaign events

Moloco Ads APIs for tracking campaign events

We provide a comprehensive set of APIs to create and manage log files of a variety of campaign-related activities such as impressions, clicks, and conversion events.

Note: The Log API is disabled by default and is only available upon request. If you would like to start using the Log API, reach out to your Moloco representative to activate.

  • Create / Read / List / Delete log data. You can create a new log object, and read, list, and delete existing log files. The log object consists of a group of parameters such as ad account, log type, log file format, and date that are needed to create log files. You can specify the following log types: IMP for impressions, CLICK for clicks, and CONVERSION for conversion events. For file format, you can specify either CSV for .csv format or AVRO for Avro. For date, you must enter the date you would like to retrieve log data for.
  • Read log status. Creating a new log object initiates the log generation process to publish the requested log file(s) on a location on the web for users to retrieve. This API lets you check the progress of this process and lets you know where you can download your log file(s).

Usage example: Create a log object

Creating a log requires the following parameters.

PropertyDescription
ad_account_idThis is the Ad Account ID for the ad account you would like to retrieve log data for.
typeThis is the type of data you would like to retrieve. Acceptable values are IMP for impressions, CLICK for clicks, and CONVERSION for conversion events.
formatThis is the format for the log file. Acceptable values are CSV for .csv format and AVRO for Avro.
dateThis is the date you would like to retrieve log data for.

The following example shows you how you can use your command line interface (CLI) to make an API request to create a log object with the request body parameters you have specified as a .json file. The parameters you have specified for the log object are saved to the .json file and delivered to the Log Creation API as an HTTP POST request body. To learn more about the parameters you can specify, see the API reference.

🚧

Keep in mind:

You will need an access token to start making API requests to Moloco Ads API. To learn how to get an access token, see Get started with Moloco Ads API.

$ 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"
}

As in this example, the response includes the following parameters. You must use the URLs returned in the response to check the progress of the log generation process and download the requested log file(s).

PropertyDescription
idThis is the Log ID, which is auto-generated by the system.
hrefThis is where you can download your log file(s). You must include the Log ID in the URL to successfully access your log file(s).
statusThis is where you can check the progress of the log generation process. You must include the Log ID in the URL to successfully view the progress.

Usage example: Check the progress of the log generation process

To check the progress of the log generation process, you must use the URL returned as part of the response to the Log Creation API request. The response returned includes the following parameters. To learn more about each of the parameters, see the API reference.

PropertyDescription
statusThis is the progress of the log generation process. Available values are ACCEPTED to indicate that the process has started, READY to indicate that the requested log file(s) are available for download, and FAILED to indicate that the process has failed to complete.
location_csvThis is the URL where you can download the requested log file(s) when the specified file format for the Log Creation API was CSV. Multiple URLs are included in the event that the amount of data to retrieve is too large.
location_avroThis is the URL where you can download the requested log file(s) when the specified file format for the Log Creation API was AVRO. Multiple URLs are included in the event that the amount of data to retrieve is too large.

In the following sample response, you can see that the log file is in .csv format, which is the format specified when creating the log object, and the value of the location_csv property is the URL for downloading the requested log file(s). You can download your log file(s) only when the value of the status property is READY as in the example.

$ 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"
  ]
}

Note: The path to the requested log file(s) (i.e., $LOG_STORAGE) is subject to change at any time and you must refrain from writing any code that makes reference to this value.


Next steps

You can generate campaign data reports to derive insights from your campaign data. To learn how to do so, see Generate campaign data reports.


What’s Next