筛选项

Reporting API

The TUNE Reporting API allows you—the advertiser—to consume reporting data generated from requests attributed and logs gathered by the Measurement API.

Setup & Essentials

Review and learn about the TUNE Server APIs. Establish core tasks, authenticate resources, create user permissions, and connect to various TUNE endpoints.

TUNE Service APIs Overview

The TUNE API is a Web service that defines a set of data interactions to its reports and other scripts. This Web service is a collection of network Endpoints, each represented by a simple HTTP URL string. Most endpoints access reports via the Web service's content, which typically comprises reports generated by data pulled from Records.

Endpoints

An Endpoint is based on an abstract definition, and can be either a "generic" or "data consumer" endpoint:

  • Data consumer endpoint represents a connection point for querying a specific record for generating reports. Most of these endpoints have read/write functionality to create/update/delete datasets from their associated records, but some only have read-only functionality.
  • Generic endpoint represents a connection point to a read-only service of a non-specific type, not bound to a record, and receives data that is of primitive types (such as string or integer).
Records

A Record represents a table in a database with fields defined by:

  • 字段名称
  • Property type -- 'string', 'integer', 'choice', 'reference', etc...
  • Default value [optional]
  • Required [default not required] -- Upon saving a new dataset, if this field is required, then a value must be provided.
  • Choices -- If property type is 'choice', then a list of allowed values is assigned.
  • Nicename [optional] -- Humanized wording for this field.

📘

重要的提示

The Property type 'reference' is an identifier to a related Record of another type. There can be multiple 'reference' fields, each uniquely associated with different Record types, including itself.

Endpoints accessing Records

A data consuming Endpoint is associated with only one Record - Endpoint and Record fields. It defines what and how information from its record is consumable by users. When an Endpoint is requested to generate a report by pulling datasets from its record, the Endpoint defines record fields that are:

  • Provided by default.
  • Extra and must be specifically requested.
  • Aggregated results across multiple datasets.

When requesting an Endpoint to generate a report, the fields to define the report uses the same name as its associated Record's fields.

Related Endpoints and Record's Referenced Records

If a data consuming Endpoint is associated with a Record that has one or more fields referencing other Records, then in turn it has Related Endpoints that are associated with those referenced Records. As with a Record with 'reference' fields as identifiers to a unique set of related Record types, then so are the set of Related Endpoints of that Endpoint (associated with said Record). For identification of Related Endpoints, an Endpoint assigns each Related Endpoint with a unique property name, which is used when a report request is to include content from its Related Endpoints' fields. If an Endpoint associated with a Record does not have 'reference' fields, then that Endpoint does not have any Related Endpoints.

Endpoint Actions

An action is an abstract description of an operation supported by an Endpoint, which can have one or more actions.

  • Actions of a Data consumer endpoint request reports/results by preparing a query to its bound Records, and possibly including its Related Endpoints.
  • Actions of a Generic endpoint request information from a service that is not data bound to any Record.

Most Data consumer endpoints have in common a set of base actions for querying and updating their bound Records (for example, 'count', 'find', 'save', 'delete', 'validate', and 'get'). An action receives requests via the query string portion of an endpoint URL. The contents of the query string must abide by the parameter signature of an action (or it will be rejected), which includes matching parameter naming, matching parameter type, and provide all required parameters. If the contents of the query string are validly submitted, then the action makes a request to its sources. Upon completion, a response is provided based on the requested result format (by default is JSON).

Common Endpoint Actions

As mentioned earlier, Data consumer endpoints represent a connection point for querying its associated record for generating reports. Most of these endpoints have read/write functionality to create/update/delete datasets from their associated records, but some only have read-only functionality.

Data consumer endpoints have a common set of actions for accessing associated records:

Endpoint描述
autocomplete.jsonFinds all existing records with name that begins with provided string referred to as parameter term.
choices.jsonFinds all existing records matching provided filter criteria and return a list of choices in the form of key record identifier => value record name pairs.
count.jsonFinds all existing records matching provided filter criteria and returns total count.
define.jsonReturns meta information for an endpoint by providing details of accessible fields with its associated record and related endpoints; for example, fields' name, type, required, and value choices if applicable.
delete.jsonDeletes an existing record by its identifier; returns model data of deleted record upon success, else if record does not exists, then status_code 404 will be tossed.
find.jsonFinds all existing records that match filter criteria and returns an array of found model data. Parameter filter syntax requirement is that can contain one or more '(field_name [=|!=|<|<=|>|>=|LIKE|RLIKE|BETWEEN] value)', matching parenthesis, joined with [AND|OR], URL encoded values (example 'Hello+World'), and no HTML tags.
find_export_queue.jsonPlaces a job into a queue to generate a report that will contain records that match provided filter criteria, and it returns a job identifier to be provided to action /export/download.json to download completed report.
get.jsonFetches existing record matching provided identifier. Returns object contain found record's contents, or status_code 404 if not found.
get_current.jsonFetches an existing record which will contain information that is only permissible for viewing by current user / context.
save.json Creates new record with data provided in an associative array of key record field name => record field value. Refer to the record' meta information using action define.json associated with this endpoint to determine fields' name, type, required, and value choices. Return model data of what was saved within new record.
validate.jsonValidates if a record exists that matches to data provided within an associative array of key record field name => record field value. If a record matches provided data, then its model data is returned. Refer to the record' meta information using action define.json associated with this endpoint to determine fields' name, type, required, and value choices.

Importance of Providing Valid Fields

It is important to understand that every endpoint has its own unique set of fields based upon the model that its data is associated with, and the model's related entities.

Making a request with a field name that does not exist with the endpoint's set of available fields can cause an internal service error (ISE) within the TUNE Management API service. So it is important to make sure that the field names used within method parameter type fieldsfiltersort, and group are appropriate to the endpoint it is calling.

Every data-consuming endpoint is associated with a single data model (hosted upon either row-oriented or column-oriented DBMS) and with zero or more related data models. When requesting a report for export from these endpoints, it is important to refer to only fields that are available to the endpoints' associated data models. Providing field names that are not associated with an endpoint's data models and included within actions' parameters will lead to:

  1. 参数 fields: Report exported will be missing column.
  2. 参数 sortgroupfilter: TUNE Management API's service will create an invalid query and thus will fail returning an "Internal Service Error" (ISE).

Understanding Action's Parameters

Action parameters allow you to customize the query to the Management API. Developers familiar with SQL should find this very familiar and easy to understand.

The power of these features is harnessed through the following API call parameters:

  • Common Parameters:
    • Parameter 'fields
    • Parameter 'filter
    • Parameter 'sort
    • Parameters 'limit' and 'page'
    • Parameters 'id' and 'ids'
    • Parameters 'key' and 'display'
    • Parameter 'model_data'
    • Parameter 'related_entities'
    • Parameter 'term'
字段

For those familiar with SQL, a field parameter is analogous to a SELECT statement, which is how you define the data you want returned for the entity. This parameter is also the mechanism by which you can get related data about an entity without having to do a secondary API call.

The fields parameter accepts a comma-separated value (CSV) list or array of field names to include, which can be the fields of the entity or related entity and/or their fields. The following examples demonstrate how to use the fields parameter in your API calls.

Parameter &fields is available for actions:

  • find.json
  • find_by_ids.json
  • get.json

Assume you're working with the /advertiser/campaigns entity:

Example 1 – Getting a subset of entity fields parameters

To limit the result to only return specific fields then set the fields parameter to a comma separated array of the specific fields you'd like returned.

fields=id,name,site_id

When the API includes the above, it would return results below:

{
  id:1,
  name:"campaign1",
  advertiser_id: 3
}
Example 2 – Getting all entity fields

To get all entity fields set the value of fields to an asterisk.

*fields =**

When the API includes the above, it would return results below:

{
  id:1,
  name:"campaign1",
  advertiser_id: 3,
  ...,
  ...,
  ...,
  all fields
}
Example 3 – Include all fields of related entity

To include all fields of a related entity simply include the entity name or include * after entity.

fields =id,name,advertiser

– or –

*fields=id,name,advertiser.**

In addition to the entities fields specified, this parameter also returns all fields of the related advertiser entity.

{
  id:1,
  name:"campaign1",
  advertiser: {
    id:3,
    name:"advertiser3",
    ...,
    ...,
    all advertiser fields
  }
}
Example 4 – Include subset of related entity fields

To include only a subset of related entity fields, simply include the specific fields after the related entity name separated by a period.

fields=id,name,advertiser.id,advertiser.name

In addition to the entities fields specified, this parameter also returns the two fields of the related advertiser entity.

{
  id:1,
  name:"campaign1",
  advertiser: {
    id:3,
    name:"advertiser3"
  }
}
Filter

For those familiar with SQL, a filter parameter is analagous to a WHERE clause.

Parameter &filter is available for actions:

  • choices.json
  • count.json
  • find.json

Filter Fields

You can include fields to filter for both the entity that you're working on, as well as its related entities (similar to the fields parameter).

Comparison Operators

Support comparison operators:

  • =
  • >
  • >=
  • <
  • <=
  • IN
  • BETWEEN
  • LIKE

Multiple Filters

You can combine filters using the AND and OR operators.

Assume you're working with the /advertiser/campaigns entity:

Example 1 – Field equals value

To filter where a field equals a value set the filter parameter accordingly. Note that the = operator needs to be URL encoded.

filter=(status = 'active')

This parameter returns only the campaigns where the status field is active.

Example 2 – Related entity field equals value

You can use related entities as the filter field by referencing them appropriately.

filter=(publisher.name = 'Ad Network 123′)

This parameter returns the campaigns where the related publisher has a name of Ad Network 123.

Example 3 – Using IN and AND

You can use the in operate like a select statement and include a comma separated array in ( ).

filter=(publisher_id in (1,2,3,4)) AND (status = 'active')

This parameter returns the campaigns where both the publisher_id = 1,2,3, or 4 AND status of the publishers is active.

Sort

The sort parameter determines the order in which results are returned.

Parameter sort is available for actions:

  • choices.json
  • find.json

The examples below assume you're working with the advertiser/campaigns entity.

Example 1 – single field sort

To sort by a single field simply include the field for the sort parameter. This sorts ascending.

sort=name

This parameter returns the campaigns by campaign name in alphabetical order (from A to Z).

Example 2 – Single field descending (aka reverse) sort

To sort descending include a colon followed by "desc" after the sort field.

sort=name:desc

This parameter returns the campaigns by campaign name in reverse alphabetical order (from Z to A).

Example 3 – Multi field sort

You can sort by multiple fields by including them in a comma separated array.

sort=advertiser_id,name:desc

This parameter returns the campaigns by advertiser id (name) in reverse alphabetical order (from Z to A).

Limit and Page for Pagination

This parameter restricts the number of results to send back. Default value is 10

ID and IDs for Record Identification

Parameter &id is used by these actions and must reference an identifier of an existing record:

  • delete.json
  • get.json

Parameter &ids is used by this action and must reference an identifier of an existing record:

  • find_by_ids.json
Model_data for Actions Save and Validate

Parameter 'data' is associated with type 'model_data'.

Term for Autocomplete

Parameter 'term' used with Action 'autocomplete' searches for a match within values of its Endpoint's auto-completion column that starts with provided string of characters, case insensitive. Typical fields assigned to auto-completion column are:

  • 'name'
  • 'email'
  • 'value'

Understanding Action's Reponse Format Choices

There are three choices result transformation of data from action results:

  • JSON success result
  • JSONP success result
  • CSV success result (limited to Action 'find')
  • JSON error
JSON Transformation

Transform output to JSON format.

示例: /controller_path/action_name.json?param_name=value&param_name=value

{
    "status_pre":200
    "response_size":"119858"
    "data":
        {
        "fields":{}
        "related_entities":
            {}
            "mod_name":"Records\Model\Advertisers"
            "mod_namespace":"Records\Model"
            "mod_shortname":"Advertisers"
        }
}
JSONP Transformation

Transform output to JSON with padding format. JSONP format requires the name of the callback function as a named query parameter value.

示例: /controller_path/action_name.jsonp?callback=jQuery0123456789&param_name=value&param_name=value

jQuery0123456789(
    {
        "status_pre":200
        "response_size":"12345"
        "data":
        {…}
    }
)
CSV Transformation

The result of this transformation is a downloadable CSV file, and it is available only to a limit set of actions. It also requires providing an array of fields, and will not default all available fields for that action's endpoint.

示例: /controller_path/action_name.csv?fields=id%2Cname%2Cemail&param_name=value&param_name=value

JSON Transformation for Error Result

If upon calling a controller it is provided with any of the following conditions, then the output will be also in JSON as shown below:

  • Invalid action name
  • Valid action provided with invalid parameters
  • Valid action provided with parameters containing invalid data

示例: /v2/controller_path/action_name.json?invalid_parameters

{
        "status_pre":401
        "response_size":"266"
        "data":
            "errors":[
            {
                "message":"API key is missing or invalid."
            ]
        }
    }

Understanding Endpoint Actions

What are Endpoint Actions?

An action is an abstract description of an operation supported by the endpoint.

If an action's endpoint is bound to a model, then it may request data underlying that model.

If an action's endpoint is not bound to a model or not, then it may perform an another service instead that excludes data access.

Calling an Endpoint Action

Defining an action is by adding a functional request + query string parameters following the endpoint's path:

  • Action name must be in lowercase, for example /find
  • Action result is transposed to JSON by adding .json
  • Required parameter for any action is either:
    • Account provided API Key (32 characters long string) and assigning it to Parameter api_key.
      For example: &api_key=aaaabbbbccccddddeeeeffffgggghhhh

Example MAT/API request with action and api_key:
https://api.mobileapptracking.com/v2/advertiser/accounts/find.json&api_key=aaaabbbbccccddddeeeeffffgggghhhh

Endpoint Action's Parameters

An action's parameters defines the request to be serviced by its controller.

Endpoint Action's Return

The return result for most actions is transposed into JSON. The following is the JSON result from /account/users/find.json:

{
  "status_code": 200,
  "response_size": "327",
  "data": [
    {
      "country_id": 840,
      "region_id": 48,
      "id": 1587,
      "type": "company",
      "name": "HasOffers Demo Account",
      "address1": "2220 Western Ave.",
      "address2": "",
      "city": "Seattle",
      "zipcode": "98121",
      "phone": "206-508-11318",
      "website": "http://www.hasoffers.com",
      "verified_phone": false,
      "status": "active"
    }
  ]
}

Understanding Endpoint and Models Fields

Endpoints that bind to Models

Only Data Consuming Endpoints have Models, thereby only these endpoints have Model fields.

These are examples of Read/Write Data Consuming Endpoints:

Service Endpoints are not bound to a record, thereby its actions are bound to a service and do not have fields:

Mapping Models Fields within Endpoint

Data Consuming Endpoints defines access to fields of the Records it is bound to be available by its actions:

Field Type描述
Default FieldsWhat fields provided default in generate result, even if no specific fields are requested.
Extra FieldsWhat fields are not included in request and must be specifically requested to be included within result.
Aggregate FieldsWhat fields when requested in result will provide an aggregate evaluation over multiple datasets.
Not Included FieldsIf so choose by the Endpoint, it can hide these fields so that they are not accessible to be included in result.
Reference FieldsThese field even though it can be included within its results, but if there is an Related Endpoint that this field identifies, it would be better to reference information via its associated Related Endpoint's property_name.field_name.
Models Fields

Records have a set of fields that provide access to its underlying data. For example, the following listing are the fields defining ModelAdvertisers, which defines the criteria for accessing this record by the Endpoint /account/ it is bound to.

To be talked about later, it is especially important to note that the model data parameter of Action save.json must be compliant to the Record fields for its dataset to be successfully received and then created. Record fields' constraints include if they are required, property type, and value choice limitation.

Those fields marked as required are expected to values when creating a dataset within Models called by via Action save.json.

Understanding Models

What are Models?

Models define the data binding for endpoints that use them.

Models enabling exchange of data representing accounts, advertisers, sites, etc. When a controller's action is requested, an entity relationship is established by creating an object instance of its associated model which adheres to the expected terms of access via their properties and relationships.

Models Bindings to Other Endpoints

Since it is an entity relationship to stored data, as set of fields and related entities are available for controllers to use, only if it so chooses to make them available through its associated actions.

Models can have a one-to-many binding to multiple endpoints, but endpoints can only be bound to one controller.

Understanding Related Endpoints and Models

Models may have identifiers which enforce links with other models, which these models would servicing the data need of other endpoints. Endpoints that have models with relations to other models, then these endpoints may expose actions to access its related endpoints.

Related Endpoints association with Endpoints are:

This endpoint is not related to any other endpoints because it associated record Users has no identifiers that are associated with these other records.

Log Endpoints v2 to v3 Migration Guide

🚧

Reporting API v2 End of Life

The v2 Reporting API for accessing log-level data is unavailable as of May 31st, 2016. All customers will be required to change their code to use the new v3 of the API, as described below.

There are substantial differences between v2 and v3 of the Reporting API Log endpoints. It is rewritten from the ground up, designed to surface new data, improve performance, lower latency, and provide stronger adherence to industry standards and conventions for RESTful APIs.

Result Set Changes

Removed fields:

  • response_size is no longer returned
  • status_code - this can be found in the http response status_code

Dot Fields (e.g. site.name) are no longer reported as a nested dictionary

Result Before:

{
             "status_code": 200,
             "data": [
                   "site_id": 12345,
                   "site": {
                         "name": "Atomic Dodgeball"
                   }
             ]
       }

Result After: (Note the "dot" in the field name 'site.name')

{
              "data": [
                    {
                         "site_id" : 12345,
                         "site.name" : "Atomic Dodgeball"
                    }
             ]
        }

Date Fields:

Dates are being returned in ISO-8601 format:

v2 date: "2016-01-06 00:05:08"
v3 date: "2016-01-06T00:05:08Z"

New Tables Available

📘

注意

Data for these three new tables is not as "fresh" as for other logs (Installs, Clicks, Events, etc.), and may run up to 6 hours behind real-time.

  • Open
  • Impressions(展示)
  • Updates

URL Path Changes

As part of making the v3 API truly RESTful, all v3 Log endpoints now use the HTTP verb GET and no longer use verbs in the path (e.g. /find.json). For this reason, the v2 actions are no longer applicable.

When using v3, your Advertiser ID must be part of the URL path as shown in the examples below in the field "advertiser_id". To request your advertiser ID, use the following v2 call:

http://api.mobileapptracking.com/v2/advertiser/find.json?api_key=yourapikey&fields=id

URL path actions that are supported under v2 but will not be supported under v3:

  • count
  • define

v2 Actions that are now accomplished via URL path differences:

The "find" action as used in v2 versus v3:

/v2/advertiser/stats//find.json
/v3/logs/advertisers//

The "findExportQueue" action as used in v2 versus v3:

/v2/advertiser/stats//findExportQueue.json
/v3/logs/advertisers//exports/

The "download" action as used in v2 versus v3:

/v2/export/download.jsonp?job_id=
/v3/logs/advertisers//exports/

Where "resource" is one of:

  • 点击次数
  • event_items (in v2 this was event/items)
  • 事件
  • 展示数
  • 安装次数
  • 打开
  • 回传
  • 更新

Parameter Differences

start_date, end_date:

  • All v3 date(time)s are ISO-8601; e.g. 2016-01-28T15:15:05Z
  • Dates without times are considered as if 12:00 AM (first moment of the day). This is different from v2 which considers a timeless end_date to be the last second of the given day.
  • Dates without offsets (i.e. a timezone) default to the value provided for the timezone parameter. If the timezone parameter is not specified, the dates timezone defaults to the timezone set in your user account. If the timezone is not set in your user account, default is UTC.
  • Offsets are defined like so: 2016-01-28T15:15:05Z-8:00 for PST; must include time for offsets to work.
  • TUNE retains data indefinitely, but data is only made available via the API for the last 120 days. This is unchanged from v2 of the API, and applies to both export and non-export queries. Supplying a start_date older than 120 days will result in an error message.

timezone:

  • Renamed from the v2 "response_timezone" parameter. If no offsets are provided in the start_date and end_date, providing timezone controls the timezone for your request's start and end date. If the timezone parameter is not specified, the dates timezone defaults to the timezone set in your user account. If the timezone is not set in your user account, default is UTC.

response_format:

  • Renamed from the v2 "format" parameter used with find_export_queue.json calls. Either JSON or CSV can be selected; defaults to JSON.
    • For synchronous search calls to override default json response:
      • v2: use "find.csv?" in endpoint
      • v3: use "response_format=csv" in parameters
    • For asynchronous export calls when starting job in order to override default CSV format:
      • v2: use "format=json" in parameters
      • v3: Not yet supported, coming soon

group:

  • No longer supported.

page:

  • No longer supported.

limit:

  • Non Export Queries:
    • The limit parameter is now required for all non-export queries. If the limit parameter is left out, an error will be issued explaining that it is required.
    • The maximum allowed limit (for non-export requests) is 5000. If more than 5000 records are requested, an error message will be issued stating the limit.
    • If more than 5000 records are required, perform an export to retrieve all the records for the given call.
  • Export Queries
    • The limit parameter is now also required for export queries.
    • The maximum allowed limit for export queries is 2 million records each. If more than 2 million records are requested, an error message will be issued stating the limit.
    • If more than 2 million records are required, please make multiple requests with smaller time intervals to pull the data needed in "batches".

sort(v2) / sorts(v3):

📘

注意

The parameter name has changed from singular, "sort", to plural, "sorts"

https://api.mobileapptracking.com/v2/advertiser/stats/installs/find?sorts=created+asc&fields=created,site&start_date=2016-01-06&end_date=2016-01-06&limit=1&api_key=yourapikey
  • The sort parameter in v2 took the form: sort[] = [desc|asc]. For example: sort[site_id]=desc&sort[country_id]=asc
  • In v3, sort has the format: sorts=<field_name> [asc|desc]. For example: sorts=site_id asc,created desc
  • In v3, sorts are not supported for related entities ("dot fields") in non-export calls. (e.g. site.name)
  • In v3, sorts are not supported for exports. If a sort parameter is supplied, an error message will be issued stating as such.

fields:

  • Fields 'profit' and 'currency_rate' are no longer available.
  • The following models are no longer available as related entities:
    • Records\Log\Clicks referenced as stat_clicks
    • Records\Log\Installs referenced as stat_installs
    • Records\Log\Updates referenced as stat_updates
    • Records\Log\Events referenced as stat_events
  • You can no longer specify entire related entity tables (for example, using fields=site,country). You must ask for the specific fields needed, for example:

之前: fields=created,site

请求:

https://api.mobileapptracking.com/v2/advertiser/stats/installs/find?fields=created,site&start_date=2016-01-06&end_date=2016-01-06&limit=1&api_key=yourapikey

响应:

{
  data: [
    {
      created: "2016-01-06 00:01:00",
      site: {
        name: "TEST APP",
        url: "",
        mobile_app_type: "iOS",
        ui_state: "",
        google_analytics: "0",
        enable_web_tracking: null,
        conversion_redirect_url: null,
        fb_app_id: "apperid",
        appsfigure_name: null,
        status: "active",
        created: "2012-09-05 19:37:15",
        modified: "2014-10-02 18:38:40",
        id: 3626,
        package_name: "20120905a",
        logo_url: "",
        logo_url_https: "",
        ref_id: null,
        store_app_id: null,
        app_channel_id: 1,
        conversion_key_id: 1708
      }
    }
  ]
 }

之后: fields=created,site.name,site.id

请求:

https://api.mobileapptracking.com/v3/logs/advertisers/877/installs?fields=created,site.name,site.id&start_date=2016-01-06T00:00:00Z&end_date=2016-01-06T23:59:59Z&limit=1&api_key=yourapikey

响应:

{
  data: [
    {
      site.id: 3626,
      created: "2016-01-06T23:59:20Z",
      site.name: "TEST APP"
    }
  ]
}

示例

v2:

https://api.mobileapptracking.com/v2/advertiser/stats/clicks/find.json

v3:

https://api.mobileapptracking.com/v3/logs/advertisers/877/clicks
  • "v3" marks this as requesting from the new API
  • "logs" is the service name and it goes right after /v3/ (replacing the less obvious "stats")
  • "877" -- the advertiser_id is part of the path.
  • "clicks" -- the log type is the same with the exception of event/items (v2) becoming event_items (v3)
  • No "find" or "count", no ".json"

Exporting one hour's worth of clicks for one specific campaign and publisher:

https://api.mobileapptracking.com/v3/logs/advertisers/1234/exports/clicks?api_key=myapikeyabcdefghijk1234567&fields=created,site.name,campaign.name,campaign_url.name,publisher.name&sorts=created desc&filter=((campaign.name='Atomic Dodgeball Campaign') AND (publisher.name='Mega Publisher'))&start_date=2015-01-31T23:00:00-800&end_date=2015-01-31T23:59:59Z&response_timezone=America/Los_Angeles

Downloading the export above:

https://api.mobileapptracking.com/v3/logs/advertisers/5490/exports/myexportkeyabcd1234?api_key=myapikeyabcdefghijk1234567

Synchronously requesting one hour's worth of clicks for one specific campaign and publisher:

https://api.mobileapptracking.com/v3/logs/advertisers/1234/clicks?api_key=myapikeyabcdefghijk1234567&limit=100&fields=created,site.name,campaign.name,campaign_url.name,publisher.name&sorts=created desc&filter=((campaign.name='Atomic Dodgeball Campaign') AND (publisher.name='Mega Publisher'))&start_date=2015-01-31T23:00:00-800&end_date=2015-01-31T23:59:59Z&response_timezone=America/Los_Angeles

Reporting API Rate Limits

The Reporting API for the TUNE Marketing Console has two types of rate limits that you may encounter when programatically requesting your reporting data; polling-related rate limiting and non-polling-related rate limiting.

Non-Polling Rate Limit

For all Reporting API calls that find and retrieve data (not download), the rate limit is 180 requests/hr.

Polling Rate Limit

For the both /export/download and the /exports/download exports endpoints, the rate limit is 408 requests/hr.

Resource Authentication & User Permissions

Calls to the TUNE API require an api_key query string parameter to be passed with each request.

  • api_key – API Keys are generated on a per-user basis, are permanent, and calls using an API Key are only allowed from devices with known IP addresses.

User Permissions with API Key

Since API Keys are on a per-user basis, they inherit the user's permissions because user permissions (ACLs) are enforced server-side in the TUNE API. Thus, the API Key should be associated with the user with the permissions you want applied.

Before using the TUNE API, you will need to create an API Key.

Generating an API Key

To generate an API Key, complete the following steps:

  1. In the navigation (on the left side), under the Accounts section, click Users.
  2. On the Users page, select the desired user.
  3. On the User Details page, click the API Keys tab (near the top), and then click Add API Key.
  4. In the Create API Key dialog box, enter a whitelisted IP address (optional), and then click Save. (These are the IP addresses that access the API. If you make your API requests from a server, then include its external IPs as well. To get your external IP address for the "Whitelist IP Addresses" list for the new API Key, visit a site like whatismyip.com.)
  5. After adding your new API Key, it's displayed in the list for that user.

If you do not have access to the Account tab, ask a co-worker (who does have access) to generate an API Key for you.