Analytics Reporting API

Overview

The 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 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

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, UAA, and Revenue.

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, uaa, revenue,
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 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

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 Parmeter 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 for an app foo

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

User Acquisition Analytics Data

Retrieve user acquisition analytics campaign performance for one day

Sample 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

Further details on User Acquisition Analytics 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

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.