imgix APIs
Management API
Reports

Reports

Note: Reports are a Premium feature and may not be enabled for all accounts. Contact Support (opens in a new tab) or your Account Manager to find out more.

Reports are updated once per day and are retained for 90 days after being finalized. Reports are finalized at 00:00 UTC and are available via API by 01:00 UTC.

They can also be downloaded in the Dashboard by accessing the Reports page (opens in a new tab).

Report Operations

Report operations require the Analytics permission.

EndpointMethodDescription
reportsGETRetrieve a list of all available reports
reports/:report_idGETRetrieve a single report by id

Report Filters

FilterTypeNotes
completedBooleanWhether report is fully completed or not.
report_typeStringReport type. See below for supported report types.

Report Sorts

  • period_end
  • period_start
  • report_key
  • report_type

Report Attributes

FieldTypeDescription
completedBooleanWhether the report is complete.
filesListList of URLs where each URL is a downloadable report. File sizes are limited to 64MB so if the report is larger than that it may be split into multiple files.
period_endIntegerEnd of the time period covered by the report, expressed as a unix timestamp.
period_startIntegerBeginning of the time period covered by the report, expressed as a unix timestamp.
report_keyStringHuman-readable ID for each report, e.g. source_analytics_20201130.
report_typeStringReport type. See below for supported report types.

Report Types

TypeDescription
cdn_logsContains daily logs for requests made to our CDN for your images. Includes information such as referrers, user agents, cache hits/misses per image, and more. Example file. (opens in a new tab)

For the referers and user_agent column, blank values indicate that there was no referer or user-agent data sent to imgix.
image_analyticsContains metrics for each Origin Image accessed that day. Includes the number of requests and errors generated by each Origin Image URL. Example file (opens in a new tab).
mild_errorsContains data related to 4xx-level errors per image. Example file (opens in a new tab).
source_analyticsContains cumulative metrics for each Source. Includes information regarding total Origin Images, total bandwidth, average response times, and more. Example file (opens in a new tab).

Since this report is cumulative, the report generated for July 31 will have Source analytics for that entire month. The report generated for July 15th will have the July Source analytics up to that day.

Report Examples

Retrieve a list of reports

GET /api/v1/reports
{
  "data": [
    {
      "attributes": {
        "completed": true,
        "files": [
          ...
        ],
        "period_end": 1601769600,
        "period_start": 1601769600,
        "report_key": "image_analytics_20201004",
        "report_type": "image_analytics"
      },
      "id": "5f7a6ab42528f162276c5584",
      "relationships": {
        ...
      },
      "type": "reports"
    },
    {
      "attributes": {
        "completed": true,
        "files": [
          ...
        ],
        "period_end": 1601769600,
        "period_start": 1601769600,
        "report_key": "source_analytics_20201004",
        "report_type": "source_analytics"
      },
      "id": "5f7a6b9a2528f16239772ab8",
      "relationships": {
        ...
      },
      "type": "reports"
    },
    ...
  ],
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      ...
    },
    "pagination": {
      "currentPage": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "nextPage": 0,
      "pageSize": 20,
      "previousPage": 0,
      "totalPages": 1,
      "totalRecords": 16
    },
    "server": {
      ...
    }
  }
}

Retrieve one report by report_id

GET /api/v1/reports/5f7676862528f12b1bfbf65b
{
  "data": {
    "attributes": {
      "completed": true,
      "files": [
          "https://storage.googleapis.com/imgix-reports/..."
      ],
      "period_end": 1601510400,
      "period_start": 1601510400,
      "report_key": "image_analytics_20201001",
      "report_type": "image_analytics"
    },
    "id": "5f7676862528f12b1bfbf65b",
    "relationships": {
      "account": {
        "data": {
          "id": "5ae39a60781cee0001020d8f",
          "type": "accounts"
        }
      }
    },
    "type": "reports"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Retrieve mild_errors report, sorted by most recent first

GET /api/v1/reports?sort=-period_end&fields[reports]=report_key,files&filter[report_type]=mild_errors
{
  "data": [
    {
      "attributes": {
        "files": [
          "https://storage.googleapis.com/imgix-reports/..."
        ],
        "report_key": "mild_errors_20201006"
      },
      "id": "5f7d0f842528f160f103836d",
      "relationships": {},
      "type": "reports"
    },
    {
      "attributes": {
        "files": [
          "https://storage.googleapis.com/imgix-reports/..."
        ],
        "report_key": "mild_errors_20201005"
      },
      "id": "5f7bbec22528f12bbde9db3d",
      "relationships": {},
      "type": "reports"
    },
    {
      "attributes": {
        "files": [
          "https://storage.googleapis.com/imgix-reports/..."
        ],
        "report_key": "mild_errors_20201004"
      },
      "id": "5f7a6bc82528f1623a2fdaf6",
      "relationships": {},
      "type": "reports"
    },
    ...
  ],
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}