Report API

What is the MOLOCO Cloud Report API

MOLOCO Cloud Report API provides customers with a comprehensive set of APIs to create reports about MOLOCO Cloud campaigns.

  • Create / Read / List / Delete reports. Conceptually, a 'report' is a group of parameters that will be used to create a report. The parameters include ad account ID, start and end date, and dimensions. A dimension is a break-down condition for the metric numbers. For example, let's say you provided 'APP_OR_SITE' as a dimension. Then the metric numbers will be grouped by per each app or site that belongs to the given ad account.
  • Read report status. Whenever a new report is created, a designated report generation job is created. What the job does is to publish the report to a location where customers can retrieve the actual report files. By calling this API, you can check the status of the job and see where you can download the report files. Currently, the reports files are in two different formats: CSV and JSON.

API flowchart

This section provides a pictorial example of how a successful report request should look like from the API layer.

Usage example: Create a Report

Creating a report is as simple as providing several parameters such as (1) your ad account ID, (2) date range for your report, and (3) the dimensions for your report break-down conditions.

Available Dimensions:

  • DATE
  • APP_OR_SITE
  • CAMPAIGN
  • CREATIVE_GROUP
  • CREATIVE
  • EXCHANGE
  • SUB_PUBLISHER
  • TRAFFIC
$ cat report.json
{
  "ad_account_id": "$AD_ACCOUNT_ID",
  "date_range": {
    "start": "2019-01-02",
    "end": "2019-01-02"
  },
  "dimensions": [
    "DATE",
    "APP_OR_SITE",
    "CAMPAIGN",
    "AD_GROUP",
    "CREATIVE_GROUP",
    "CREATIVE",
    "EXCHANGE",
    "SUB_PUBLISHER",
    "TRAFFIC"
  ]
}

$ curl -X POST \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d "@report.json" \ https://api.moloco.cloud/cm/v1/reports 

{
  "id": "$REPORT_ID",
  "href": "https://api.moloco.cloud/cm/v1/reports/$REPORT_ID",
  "status": "https://api.moloco.cloud/cm/v1/reports/$REPORT_ID/status"
}

In this example, your report generation parameters are in the report.json file and delivered to the Report Creation API as an HTTP POST request body. Please change $AD_ACCOUNT_ID with the real ad account ID.

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

In most cases, what you want to do after calling the Report Creation API is to access the URI returned in the status field because probably you want to see the actual report.

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

Usage example: Access a Report

Access the report is as simple as calling the URI endpoint returned in status field in the body of the Report Creation API call result.

$ curl \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
https://api.moloco.cloud/cm/v1/reports/$REPORT_ID/status

{
  "status": "READY",
  "location_json": "https://$REPORT_STORAGE/$REPORT_ID.json",
  "location_csv": "https://$REPORT_STORAGE/$REPORT_ID.csv",
}

In the above example response body, you can find that there are 2 different report files provided for your convenience: (1) CSV, and (2) JSON.

Once the value of the field status is changed into READY as in the example, you can download the report files from the location given in location_json and location_csv.

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

Schema of JSON file

The JSON report file conforms to the following JSON schema.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Contents of a report JSON file consisting of rows.",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Row"
      },
      "description": "Rows of the report."
    }
  },
  "definitions": {
    "Row": {
      "type": "object",
      "description": "A row in the report table consisting of columns.",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in \"yyyy-mm-dd\" format."
        },
        "ad_account": {
          "$ref": "#/definitions/AdAccountColumn",
          "description": "AdAccount column."
        },
        "app": {
          "$ref": "#/definitions/AppColumn",
          "description": "App column."
        },
        "site": {
          "$ref": "#/definitions/SiteColumn",
          "description": "Site column."
        },
        "campaign": {
          "$ref": "#/definitions/CampaignColumn",
          "description": "Campaign column."
        },
        "ad_group": {
          "$ref": "#/definitions/AdGroupColumn",
          "description": "Ad-group column."
        },
        "creative_group": {
          "$ref": "#/definitions/CreativeGroupColumn",
          "description": "Creative-group column."
        },
        "creative": {
          "$ref": "#/definitions/CreativeColumn",
          "description": "Creative column."
        },
        "exchange": {
          "$ref": "#/definitions/ExchangeColumn",
          "description": "Exchange column."
        },
        "sub_publisher": {
          "$ref": "#/definitions/SubPublisherColumn",
          "description": "Sub-publisher column."
        },
        "traffic": {
          "$ref": "#/definitions/TrafficColumn",
          "description": "Traffic column."
        },
        "metric": {
          "$ref": "#/definitions/MetricColumn",
          "description": "Metric column."
        },
        "skan": {
          "$ref": "#/definitions/SKANColumn",
          "description": "SKAN column."
        },
        "skan_metric": {
          "$ref": "#/definitions/SKANMetricColumn",
          "description": "SKAN Metric column."
        }
      }
    },
    "AdAccountColumn": {
      "type": "object",
      "description": "AdAccountColumn represents a structured column containing ad-account information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an ad-account."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of an ad-account."
        },
        "currency": {
          "type": "string",
          "description": "Contract currency in ISO-4217."
        }
      }
    },
    "AppColumn": {
      "type": "object",
      "description": "AppColumn represents a structured column containing app information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an App."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of an App."
        },
        "store_id": {
          "type": "string",
          "description": "ID of an App in the store."
        },
        "os": {
          "type": "string",
          "description": "OS type of an App."
        }
      }
    },
    "SiteColumn": {
      "type": "object",
      "description": "SiteColumn represents a structured column containing site information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a Site."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a Site."
        },
        "domain": {
          "type": "string",
          "description": "Domain of a Site."
        }
      }
    },
    "CampaignColumn": {
      "type": "object",
      "description": "CampaignColumn represents a structured column containing campaign information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a campaign."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a campaign."
        },
        "country": {
          "type": "string",
          "description": "Country code in ISO-3166 Alpha-3."
        }
      }
    },
    "AdGroupColumn": {
      "type": "object",
      "description": "AdGroupColumn represents a structured column containing ad-group information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an ad-group."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of an ad-group."
        }
      }
    },
    "CreativeGroupColumn": {
      "type": "object",
      "description": "CreativeGroupColumn represents a structured column containing creative-group information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a creative-group."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a creative-group."
        }
      }
    },
    "CreativeColumn": {
      "type": "object",
      "description": "CreativeColumn represents a structured column containing creative information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a creative."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a creative."
        },
        "type": {
          "type": "string",
          "description": "Type of a creative."
        },
        "main_asset_location": {
          "type": "string",
          "description": "URL of the main asset of a creative."
        }
      }
    },
    "ExchangeColumn": {
      "type": "object",
      "description": "ExchangeColumn represents a structured column containing ad-exchange information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an exchange."
        }
      }
    },
    "SubPublisherColumn": {
      "type": "object",
      "description": "SubPublisherColumn represents a structured column containing sub-publisher information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a sub-publisher."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a sub-publisher."
        }
      }
    },
    "TrafficColumn": {
      "type": "object",
      "description": "TrafficColumn represents a structured column containing traffic information.",
      "properties": {
        "is_lat": {
          "type": "boolean",
          "description": "Flag indicating whether the bid was served with is_lat on or not."
        },
        "skan_bid": {
          "type": "boolean",
          "description": "Flag indicating whether the bid of the traffic includes a bid response for SK AdNetwork."
        },
        "mmp_effective": {
          "type": "boolean",
          "description": "Flag indicating whether the conversions from the bid can be attributed by MMP."
        }
      }
    },
    "MetricColumn": {
      "type": "object",
      "description": "MetricColumn represents a structured column containing metric numbers.",
      "properties": {
        "impressions": {
          "type": "string",
          "format": "int64",
          "description": "The number of impressions."
        },
        "clicks": {
          "type": "string",
          "format": "int64",
          "description": "The number of clicks."
        },
        "installs": {
          "type": "string",
          "format": "int64",
          "description": "The number of installs."
        },
        "spend": {
          "type": "number",
          "format": "double",
          "description": "The amount of ad spend in contract currency."
        },
        "revenue": {
          "type": "number",
          "format": "double",
          "description": "The amount of revenue in contract currency."
        }
      }
    },
    "SKANColumn": {
      "type": "object",
      "description": "SKANColumn represents a structured column containing SK AdNetwork  information.",
      "properties": {
        "conversion_value": {
          "type": "string",
          "description": "Conversion Value sent by Apple through SK AdNetwork postback."
        }
      }
    },
    "SKANMetricColumn": {
      "type": "object",
      "description": "SKANMetricColumn represents a structured column containing metric numbers related to SK AdNetwork information.",
      "properties": {
        "conversion_count": {
          "type": "string",
          "format": "int64",
          "description": "The number of counts associated with the corresponding conversion_value."
        }
      }
    }
  }
}

Frequently Asked Questions

Why is my report taking so long to load?
The size of the report depends on the date range and dimensions selected in your request. To reduce the time taken to load the report, consider selecting a shorter date range or reducing the number of dimensions in your report.

Where do I get the $ID_TOKEN?
The ID_TOKEN is a temporary authentication token that has to be generated by a POST request. Please follow the steps to generate it here.

If I wish to get the full data for the latest day in the report, when would be a good time to run the report?
The data is updated every hour so it's always recommended to retrieve the previous day's data after 3 AM (in your respective timezone) on the current day in order to ensure that you get the full day's data for the previous day.