Analytics Reporting API

Overview

Flurry Analytics provides you with the tools and resources you need to gain a deep level of understanding about your users’ behavior in your apps. Flurry Metrics API allows you to export your data, based on standard formats such as CSV and JSON, allowing you to integrate it into web dashboards, data warehouses and any other system you might use for managing your business.

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

Authorization: Bearer programmatic_token_here

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

The metrics (reporting) API is organized by tables (product features), currently allowing for independent reporting on App Usage, App Events and Event Params, Real Time, Audience, Technical, Revenue, Crash Report, and Crash Summary Report.

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

appUsage, appEvent and eventParams, realTime, audience, technical, revenue, crashReport, crashSummaryReport

timeGrain

yes

day, week, month, … Table specific. See table details

dimension

no

app, company, country,…Table specific. See table details.

metrics

yes

sessions, activeDevices, …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 the 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. Can be combined with 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-notgt[200]

format

no

json (default), csv

timeZone

no

Default results are in UTC time zone.

Format:

Example: America/New_York or America/Los_Angeles https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

App Usage Data

To get data on session, new, active devices, time spent,.. in your apps check the appUsage table.

Sample request:

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

Further details on App Usage table.

App Event Data

Full on reporting on how often an Event occurs, how many unique users trigger an Event, etc.

Sample 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]

Further details on App Event table.

App Event Parameter Data

If you have added parameters to your Event, you can get the report on their occurence

Sample 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

Further details on App Event Parameter table.

Real Time App Data

Real time app data provides you with real-time data on how your app may be impacted by user updates, user acquisitions, or enhancements.

Sample 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]

Further details on Real Time table.

Audience Data

To understand your app audience, including their age and gender, retrieve data from the audience table.

Sample Request:

https://api-metrics.flurry.com/public/v1/data/audience/day/app/generalInterestCategory?metrics=activeDevices&dateTime=2017-04-01/2017-04-02&filters=app|name-in[foo]

Further details on Audience Data table.

Technical Data

Retrieve activeDevices metric broken out by top 3 carriers.

Sample Request:

https://api-metrics.flurry.com/public/v1/data/technical/day/app/carrier?metrics=activeDevices&dateTime=2017-04-01/2017-04-02&filters=app|name-in[foo]&topN=3&sort=activeDevices

Further details on Technical Data table.

Revenue Analytics Data

Retrieve IAP purchases for one day for all company apps broken out by each product with revenue in USD.

Request:

https://api-metrics.flurry.com/public/v1/data/iapRevenue/day/app/product?metrics=revenueUSD,purchases,purchaseQuantity&dateTime=2017-04-01/2017-04-02&sort=revenueUSD

Further details on Revenue Analytics Data table.

Retention Data (Beta)

We recognize that retention analysis is very powerful to understand the health and viability of your app. You can now query retention metrics for an individual app or at company level.

Sample Request:

https://api-metrics.flurry.com/public/v1/data/retention/day?metrics=returnRate,rollingRate&dateTime=2018-01-08/2018-01-15&filters=app|apiKey-in[<flurry_api_key_here>]&token=<programmatic_token>

Further details on Retention Data table.

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/dimension 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 a maximum of 50,000 rows in the response. Modify your query to request 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 and 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 the 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.

  • The maximum interval supported at this time is 90 days in one single request. Since the API request is a synchronous call to the server, limiting this period allows for faster response to queries. For gathering data for longer periods, please split query into multiple time period queries.

  • Missing timestamps for scenarios where there are no results for a combination of timestamp, dimensions and any filter criteria, the result timestamps are omitted completely. This is done to reduce the 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, the metric needs to be part of the API data request.

  • Additional dimension attributes can be requested by adding the show clause next to dimension breakdown on the API request. Without the show clause, only dimension name attributes will be included on the result. The how 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 sets 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.