Analytics Reporting API

Overview

Flurry Metrics API allows developers to consume Flurry Analytics and/ or Publishing metrics outside of Flurry Developer Portal. This new API replaces an older version that provided access to limited reporting capabilities.

To get the access to your company data you need to acquire the programatic app token. The programatic token should be included in the header as:

Authorization: Bearer

Flurry Analytics API Query Builder

We’ve created an api console which you can use to build test queries and experiment with our API.

API basics

Metrics API endpoint is https://api-metrics.flurry.com/public/v1/data/

The API request comprises of elements that can be combined to query your analytics data. Everything in the API is case-sensitive.

endPoint/table/timeGrain/dimension1/dimension2;show=all/dimension3{...}?metrics=[comma-separated-metrics]&dateTime=[..]&filters=[...]&topN=[..]&sort=[..]&having=[..]&format=[..]&timeZone=[..]

Params Required Example
endpoint yes v1: https://api-metrics.flurry.com/public/v1/data/
table yes see section 3
timeGrain yes Table specific. See table details.
dimension no Table specific. See table details.
metrics yes Table specific. See table details.
dateTime yes Format for Day, Week: YYYY-MM-DD/YYYY-MM-DD Format for Month: YYYY-MM/YYYY-MM Format for Hour: YYYY-MM-DDTHH/YYYY-MM-DDTHH (HH in 24- hour format) follows ISO 8601
filters no

One or more dimension attribute filters that are combined (as AND) to reduce output to match your criteria. id and name are available for all dimensions. some dimensions have additional attributes that are called out in dimensions section.

Format: dimension1|attribute-operator[value(s)], dimension2|attribute-operator[value(s)]

Operators: in, notin, contains, startsWith

Example: country|name-in[‘United States’,‘Canada’,’Mexico’] ,appVersion|name-in[‘2.3’]

sort no

Specify one or more metrics to sort results by. If order is not specified, then it defaults to descending.

Example: sort=sessions|desc,activeDevices|desc

topN no

reduces result to match the number specified for this parameter. If this parameter is used, then you must also use sort to indicate metric and order by which top n must be calculated

Example: topN=5&sort=sessions|desc

having no

reduces result to match the metrics criteria specified. you can combine multiple metrics criteria.

Format: metric-operator[value(s)]

Operators available: equal(eq), greaterThan(gt), lessThan(lt) and their not versions

Example: sessions-gt[1000],activeDevices-gt[200]

format no json (default), csv
timeZone no

default results are in UTC time zone. to get results in your desired time zone, use this parameter.

Format:

Example: America/New_York or America/Los_Angeles

https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Analytics Metrics

Below are metrics that are available for reporting.

Metric Description
sessions number of times users accessed the application
activeDevices total unique devices that accessed the application
newDevices new devices that installed and launched the application
timeSpent time users spent in the application
averageTimePerDevice average time users spent in the application per device
averageTimePerSession average time users spent in the application per session
medianTimePerSession median time users spent in the application per session
averageTimePerSession average time users spent in the application per session
occurrences number of times an event occurred
count number of times specific value was recorded for an event param

Analytics Dimensions

Below are dimensions and dimension attributes that are available for reporting.

Dimension Description Value
company Flurry company account id, name (default)
app Flurry app id, name (default), company|id, apiKey, platform|id, platform|name
country Per country dimension totals id, name (default), iso
appVersion App’s version id, name, company id, app id, deleted and filtered. Deleted and filtered are boolean (0 or 1) and reflect current status of an app version based on developer’s action on Flurry developer portal id, name (default), company|id, app|id, deleted, filtered
language Language id and name id, name (default)
region Region id and name id, name (default)
category App category id and name id, name (default)
event Availble for appEvent table only; Event id, name, app id, company id, deleted and filtered. Deleted and filtered are boolean (0 or 1) and reflect current status of an app event based on developer’s action on Flurry developer portal. id, name (default) , company|id, app|id, deleted, filtered
paramName Name of event param. Available for eventParams table only; Param id, name  
paramValue Value of event param. Available for eventParams table only; Value id, name  

There are instances when you want to know the possible values for dimensions before running metric queries. For example: list names and api keys for all apps on your company account

https://api-metrics.flurry.com/public/v1/data/appUsage/day/company/app;show=name,apiKey?metrics=...

In general, to see a value other than defalut name returend for the given dimension, add

;show=all
or
;show=id  (any other value listed in the value column above for the given dimension

after the dimension name

https://api-metrics.flurry.com/public/v1/data/appUsage/day/company/country;show=all/category?metrics=sessions,activeDevices,newDevices,timeSpent&dateTime=2017-05-01/2017-05-02

https://api-metrics.flurry.com/public/v1/data/appUsage/day/company/country;show=iso/category?metrics=sessions,activeDevices,newDevices,timeSpent&dateTime=2017-05-01/2017-05-02

App Usage Data

Table: appUsage

Metrics Dimensions Time Grain
sessions company day
activeDevices app week
newDevices appVersion month
timeSpent country all
averageTimePerDevice language  
averageTimePerSession region  
medianTimePerSession category  

Example key app metrics queries

For all your apps, daily Sessions, daily Active Devices, New Devices for 2 days*: * note that since there is no app info included in the filter, results will include all apps for your company

Request:

https://api-metrics.flurry.com/public/v1/data/appUsage/day/app?metrics=sessions,activeDevices,newDevices&dateTime=2016-07-01/2016-07-03

Response:

{
        "rows": [{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "sessions": 372,
                "activeDevices": 123,
                "newDevices": 32},
        {
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "bar",
                "sessions": 1120,
                "activeDevices": 487,
                "newDevices": 34},
        {
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "sessions": 421,
                "activeDevices": 140,
                "newDevices": 12},
        {
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "bar",
                "sessions": 1164,
                "activeDevices": 453,
                "newDevices": 51}]
}

For a specific app, daily Sessions, Active Devices and New Devices for 2 months:

Request using Flurry API key:

https://api-metrics.flurry.com/public/v1/data/appUsage/day?metrics=sessions,activeDevices,newDevices&dateTime=2016-06-01/2016-08-01&filters=app|apiKey-in[3WD7Q8329867K7MY6RNS]

Request using App name:

https://api-metrics.flurry.com/public/v1/data/appUsage/day?metrics=sessions,activeDevices,newDevices&dateTime=2016-06-01/2016-08-01&filters=app|name-in[appname]

Response:

{
        "rows": [{
                "dateTime": "2016-06-01 00:00:00.000-07:00",
                "app|name": "foo",
                "sessions": 12744,
                "activeDevices": 6373,
                "newDevices": 6373
        },{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "sessions": 13805,
                "activeDevices": 6882,
                "newDevices": 6882
        }]
}

App Events Data

Table: appEvent

Metrics Dimensions Time Grain
activeDevices company day
newDevices app week
eventDuration appVersion month
averageTimePerDevice country all
averageTimePerSession language  
medianTimePerSession region  
occurrences category  
  event  

Example key app event metrics queries

For a specific app events, event occurrences broken by app version for 2 days:

Request:

https://api-metrics.flurry.com/public/v1/data/appEvent/day/app/appVersion/event?metrics=occurrences&dateTime=2016-07-01/2016-07-03&filters=app|name-in[foo],event|name-in[login,register]

Response:

{
        "rows": [{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "occurrences": 293
        },{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "register",
                "occurrences": 57
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "occurrences": 146
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "register",
                "occurrences": 31
        }]
}

For a specific app event, Active Devices and New Devices for Top 5 Countries sorted by Active Devices for 2 days:

Request:

https://api-metrics.flurry.com/public/v1/data/appEvent/day/app/country?metrics=activeDevices,newDevices&dateTime=2016-07-01/2016-07-03&filters=app|name-in[foo],event|name-in[login]&topN=5&sort=activeDevices|desc

Response:

{
        "rows": [{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "United States",
                "occurrences": 515
        },{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "United Kingdom",
                "occurrences": 210
        },{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "Canada",
                "occurrences": 165
        },{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "Germany",
                "occurrences": 87
        },{
                "dateTime": "2016-07-01 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "France",
                "occurrences": 46
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "United States",
                "occurrences": 435
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "United Kingdom",
                "occurrences": 190
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "Canada",
                "occurrences": 127
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "Germany",
                "occurrences": 76
        },{
                "dateTime": "2016-07-02 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "country|name": "France",
                "occurrences": 39
        }]
}

App Event Parameter Data

Table: eventParams

Metrics Dimensions Time Grain
count company day
  app week
  appVersion month
  country all
  language  
  region  
  category  
  event  
  paramName  
  paramValue  

Example app event parameter metrics query

For a specific app event, provide event parameter values breakdown for 1 day:

Request:

https://api-metrics.flurry.com/public/v1/data/eventParams/day/app;show=all/event/paramName/paramValue?metrics=count&filters=app|name-in[foo],event|name-in[level_complete]&dateTime=2016-11-07/2016-11-08

Response:

{
        "rows": [{
                "dateTime": "2016-11-07 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "level_complete",
                "paramName|name": "level",
                "paramValue|name": "1",
                "count": 32
        },{
                "dateTime": "2016-11-07 00:00:00.000-07:00",
                "app|name": "foo",
                "event|name": "login",
                "paramName|name": "level",
                "paramValue|name": "2",
                "count": 15
        }]
}

Real Time App Data

Table: realtime (recent 48 hours)

Metrics Dimensions Time Grain
sessions company hour
activeDevices app day
  appVersion all
  country  

Example real time* metrics queries * last 48 hours only

For a specific app, Sessions and Active Devices in a specific hour:

Request:

https://api-metrics.flurry.com/public/v1/data/realtime/hour?metrics=sessions,activeDevices&dateTime=2016-08-27T12/2016-08-27T13&filters=app|name-in[foo]

Response:

{
        "rows": [{
                "dateTime": "2016-08-31 12:00:00.000-07:00",
                "app|name": "foo",
                "sessions": 145,
                "activeDevices": 90
        }]
}

For a specific app, total Sessions and Active Devices broken by app version in a specific 24 hour period (not day boundary):

Request:

https://api-metrics.flurry.com/public/v1/data/realtime/all/app/appVersion?metrics=sessions,activeDevices&dateTime=2016-08-31T12/2016-09-01T13&filters=app|name-in[appname]

Response:

{
        "rows": [{
                "dateTime": "2016-08-31 12:00:00.000-07:00",
                "app|name": "foo",
                "appVersion|name": "1.0",
                "sessions": 231,
                "activeDevices": 87
        },{
                "dateTime": "2016-08-31 12:00:00.000-07:00",
                "app|name": "foo",
                "appVersion|name": "1.1",
                "Sessions": 345,
                "activeDevices": 167
        }]
}

User Acquisition Analytics Data

Table: appUsage

Metrics Dimensions Time Grain
campaignClicks company day
campaignConversions app week
campaignConversionRate country month
  category all
  campaign  
  channel  

Example key app metrics queries

Retrieve user acquisition analytics campaign performance for one day

Request:

https://api-metrics.flurry.com/public/v1/data/attribution/day/app/category/campaign?metrics=campaignClicks,campaignConversions,campaignConversionRate&dateTime=2017-05-01/2017-05-02

Response:

{
        "rows": [{
                "dateTime": "2017-05-01 00:00:00.000-07:00",
                "app|name": "foo",
                "category|name": "News",
                "campaign|name": "news Q2 2017",
                "campaignClicks": 10,
                "campaignConversions": 1,
                "campaignConversionRate": 0.1
        },{
                 "dateTime": "2017-05-01 00:00:00.000-07:00",
                 "app|name": "bar",
                 "category|name": "Shopping",
                 "campaign|name": "Summer Q2 2017 - US",
                 "campaignConversions": 2,
                 "campaignClicks": 10,
                 "campaignConversionRate": 0.2
        },{
                 "dateTime": "2017-05-01 00:00:00.000-07:00",
                 "app|name": "bar",
                 "category|name": "Shopping",
                 "campaign|name": "Summer Q2 2017 - Europe",
                 "campaignConversions": 5,
                 "campaignClicks": 100,
                 "campaignConversionRate": 0.05
        }]
}

Errors

Code Name What to do
400 BAD REQUEST You have some sort of syntax error in your request. We couldn’t figure out what you were trying to ask. Check your request format.
401 UNAUTHORIZED We don’t know who you are, so send your request again, but tell us who you are. Usually this means you didn’t include proper token authentication information in your request.
403 FORBIDDEN We know who you are, but you can’t come in. This is usually because you’re making a request to access data from a company or app to which you do not have access. Please select ‘Viewer’ role to enable programmatic API access using your account. If you leave it as ‘None’, then you will not be able to access metrics via API
404 NOT FOUND We don’t know which resource you are requesting. You probably have a typo in your URL path.
416 REQUESTED RANGE NOT SATISFIABLE We can’t get that data for you. Time range is too large or not available for reporting.
422 UNPROCESSABLE ENTITY We understood the request (ie. syntax is correct), but something else about the query is wrong. Likely something like a dimension mis-match, or a metric / dimen- sion not being available in the requested table.
429 TOO MANY REQUESTS You’ve hit the rate limit. Wait a little while for any requests you may have sent to finish and try your request again.
5xx INTERNAL SERVER ERROR Some other error on our end. We try to catch and investigate all of these, but we might miss them, so please let us know if you get 5XX errors.
500 MAXIMUM NUMBER OF ROWS REACHED Our API retruns max 50,000 rows in the response. Modify your query to request a smaller scope
507 INSUFFICIENT STORAGE The query was deemed too costly to run and rejected.

Additional Clarification/ Tips

  • Case sensitive API is case sensitive. This means that metric, dimension and API request parameter names must be spelled as specified in the document. sessions is not the same as Sessions is not the same as SeSsIoNs.
  • Specifying time intervals: dateTime follows ISO 8601 for start and end period. Start date time period is included but end date time interval is excluded from query interval
  • Week/ Month time grains require specifying the exact start and end boundary dates for query to be well formed. Month queries must specify first of the month for both start and end period. Week queries must specify dates for Monday of the week for corresponding start and end periods.
  • Max interval supported at this time is 90 days in one single request. Since the API request is a synchronous call to server, limiting this period allows for faster response to queries. For gathering data for longer periods, please split query for multiple time periods.
  • Missing timestamps For scenarios where there are no results for a combination of timestamp, dimensions and any filter criteria, timestamps are omitted completely. This is done to reduce size of results and for faster response to queries.
  • Filter can only be applied on dimensions that are included in the results requested.
  • Sorting applies for results within a specific timestamp. This means that results are always ordered first by timestamp and then by any sort criteria that you added to the API request. Also to sort on a metric, requires the metric to be part of API data request.
  • Additional dimension attributes can be requested by adding show clause next to dimension breakdown on the API request. Without show clause, only dimension name attribute will be included on the result. Show clause must include comma separated dimension attributes or all.
  • Rate limits To prevent abuse of the system, the API only allows each user to have a certain number of data requests being processed at any one time. If you try to make another request that would put you above the allowed limit, you will be given an error response with an HTTP response status code of 429.
  • The following headers will be returned with a 429 response:
    • X-RateLimit-Limit The maximum number of credits that the consumer is permitted to charge. All requests consume at least 1 credit but can cost more depending on the resources consumed.
    • X-RateLimit-Remaining The number of credits remaining. This number can go negative.
    • X-RateLimit-RefillPerMinute The rate (credits/minute) at which credits are refilled.
  • Programmatic accounts are specific to one company only. Even though you may have access to multiple companies, a programmatic account grants API authorization to one company only. You can have multiple accounts that have access to different set of apps in case your company/ app team organization requires such a configuration.
  • Forgotten/ lost/ compromised programmatic tokens require that you delete the programmatic account that you or your company admin created and create a new programmatic account. You will then need to replace the old token with this newly created programmatic account.
  • Retention metric is currently unavailable in New Metrics API. We’re working on adding it soon.