Overview
Reporting API is a premium feature. To enable the reporting API, please contact sales@imgix.com
The reports API allows you to request more granular reporting for images within your Sources by creating a cURL request. Here's an example of a report request using cURL:
curl -u "<API_KEY>:" "https://api.imgix.com/v2/account/reports"
Make a request
Before you begin making a report request using our API, it's important you first install cURL for your command line.
Once installed, you can follow the steps below to make a request to our reporting API:
- Open your command line
- Use the command
curl -u "<API_KEY>:" "https://api.imgix.com/v2/account/reports"- Replace <API_KEY> with your own API key. You can get this within your imgix account settings.
- You will receive a JSON response with a list of reports, their report types and a file link to download the report
Note that the file links automatically expire after a period of time. You can regenerate new links by making another request to our reporting API.
Parameters
You can apply parameters to fine tune your report request. The available parameters are:
sort: The field to sort on.
order: "desc" will trigger descending order.
limit: The maximum number of records to return.
offset: The first n records to skip (useful when sorting).
filter[key]: Filter on key.
Here's an example of a report with parameters applied:
curl -u "<API_KEY>:" "https://api.imgix.com/v2/account/reports?limit=5&sort=report_key&order=desc&offset=9
Types of reports
Image analytics
The image analytics report contains daily metrics for each origin image, updated once a day. It includes the number of requests and errors generated by each image. You can download an example here:
https://storage.googleapis.com/imgix-public/Image-Analytics-Reports-Example.csv
Source analytics
The Source analytics report contains cumulative metrics for each Source, uploaded each day. It includes information regarding total origin images, total bandwidth, average response times and more. You can download an example here:
https://storage.googleapis.com/imgix-public/Source-Analytics-Report-Example.csv
Since this report is cumulative, this means that the CSV generated for July 31 will have Source analytics for that entire month. Having a CSV generated for July 15th will have the Source analytics leading up to that day.
CDN logs
The CDN logs report contains daily logs for requests made to our CDN for your images, updated once a day. It will include information such as referrers, user agents, cache hits/misses per image and more. You can download an example here:
https://storage.googleapis.com/imgix-public/CDN-Logs-Report-Example.csv
Mild errors
The mild errors report contains data regarding the number of 4xx level errors that occur per image, updated once per day. You can download an example report here:
https://storage.googleapis.com/imgix-public/Mild-Errors-Report-Example.csv
What time do reports run?
Reports are finalized at 00:00 UTC time and are retrievable by the API at around 01:00 UTC time.
Troubleshooting
429 - Request has timed out
Your request to the API may time out if there are too many results to return. You can solve this by setting a limit on the number of records fetched using the limit parameter. Example:
curl -u "<API_KEY>:" "https://api.imgix.com/v2/account/reports?limit=5
See the Parameters section above in order to find more information on sorting through reports.
Alternatively, if the reporting API is not enabled, you may also encounter the 429 error response code regardless of how many requests you send. Please contact support@imgix.com to verify and look into this issue.