Reports

Note: The Image Analytics report is available to all paid customers, however other reports are a Premium feature and may not be enabled for all accounts. Contact Support 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 04:00 UTC.

They can also be downloaded in the Dashboard by accessing the Reports page.

Report Operations

Report operations require the Analytics permission.

Endpoint	Method	Required Permissions	Description
`reports`	GET	Analytics	Retrieve a list of all available reports
`reports/:report_id`	GET	Analytics	Retrieve a single report by `id`

Report Filters

Filter	Type	Notes
`completed`	Boolean	Whether report is fully completed or not.
`report_type`	String	Report type. See below for supported report types.

Report Sorts

period_end
period_start
report_key
report_type

Report Attributes

Field	Type	Description
`completed`	Boolean	Whether the report is complete.
`files`	List	List 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_end`	Integer	End of the time period covered by the report, expressed as a unix timestamp.
`period_start`	Integer	Beginning of the time period covered by the report, expressed as a unix timestamp.
`report_key`	String	Human-readable ID for each report, e.g. `source_analytics_20201130`.
`report_type`	String	Report type. See below for supported report types.

Report Types

Type	Description
`cdn_logs`	Contains 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. For the `referers` and `user_agent` column, blank values indicate that there was no `referer` or `user-agent` data sent to Imgix.
`credit_analytics_daily`	Contains per-Source credit consumption for a single day. One row per Source, covering the credits that Source consumed on the report date only. See Credit Analytics Reports for the column breakdown. Generated automatically for any account with the `source_analytics` report enabled.
`credit_analytics_mtd`	Contains per-Source credit consumption month-to-date. One row per Source, covering the credits that Source has consumed cumulatively from the 1st of the month through the report date. Resets to zero at the start of each calendar month. See Credit Analytics Reports for the column breakdown. Generated automatically for any account with the `source_analytics` report enabled.
`image_analytics`	Contains cumulative metrics for each Origin Image accessed throughout the current month. Includes the total number of requests, bandwidth and errors generated by each Origin Image URL. Example file.
`mild_errors`	Contains data related to `4xx`-level errors per image. Example file.
`source_analytics`	Contains cumulative metrics for each Source. Includes information regarding total Origin Images, total bandwidth, average response times, and more. Example file. 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.

Credit Analytics Reports

The credit_analytics_mtd and credit_analytics_daily reports break down an account’s credit consumption per Source. They are generated automatically for any account that has the source_analytics report enabled — no separate setup is required.

Both reports share identical columns and layout; they differ only in the time window they cover:

credit_analytics_mtd — month-to-date credit totals, cumulative from the 1st of the month through the report date. A value on the 22nd reflects usage since the 1st of that month, not a rolling 30-day or all-time figure. Resets to zero at the start of each calendar month.
credit_analytics_daily — credits consumed on the report date only.

Each report is delivered as a gzipped CSV with a header row (one file per account per day, which may be split into multiple files for large accounts), with one row per Source. Reports are generated daily and reflect the finalized credit figures for the prior day.

Columns

Column	Description
`timestamp`	The report date.
`source_id`	imgix Source ID.
`source_name`	Source name. May be blank if the Source has since been deleted or renamed.
`total_credits`	Total credits consumed. This is the authoritative figure — it is the sum of all credit categories, including any not individually listed below, so it may be larger than the sum of the listed columns when a newer credit type is not broken out separately.
`standard_renders_credits`	Standard image render credits.
`advanced_renders_credits`	Advanced image render credits.
`premium_renders_credits`	Premium image render credits.
`storage_credits`	Storage credits.
`delivery_bandwidth_credits`	Delivery bandwidth credits.
`cache_reads_credits`	Cache read credits.
`premium_video_encoding_seconds_credits`	Premium video encoding credits.
`video_smartcropping_seconds_credits`	Video smart-cropping credits.
`video_preview_seconds_credits`	Video preview credits.
`video_ai_interpolation_seconds_credits`	AI video interpolation credits.
`video_vmaf_encoded_seconds_credits`	VMAF video encoding credits.
`video_render_cache_credits`	Video render cache credits.
`specialized_transformations_credits`	Specialized transformation credits.

All credit values are numeric, and timestamp is expressed as a date.

Note: Some newer video credit types — AI interpolation, VMAF encoding, and video render cache — currently report 0, as those features are not billing credits yet. The columns already exist and will populate automatically once those credit types go live.

Report Examples

Retrieve a list of reports

# Request
GET /api/v1/reports

# Response
{
  "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`

# Request
GET /api/v1/reports/5f7676862528f12b1bfbf65b

# Response
{
  "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

# Request
GET /api/v1/reports?sort=-period_end&fields[reports]=report_key,files&filter[report_type]=mild_errors

# Response
{
  "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": {
    ...
  }
}

Purges Sources