Reports API

You can use the Reports API to set up reports on the archive, run them on a schedule or on demand, and download the results. A report configuration says what a report contains and when it runs. Each time it runs, the archive generates a report file, which you can list and download.

Every call needs the headers in Common headers.

Report types

Pick the report type that matches the data that you want:

• packages_query: a CSV file with one row per package that matches your query.

• aggregate_packages_query: a CSV file with counts of packages over time.

• report_collection_query: a CSV file that summarizes the events that a notification configuration logs. To log events, see Notifications API.

Set outputFormat to CSV for all of them. The CSV files use a semicolon (;) between values.

List report configurations

GET /v2/report-configs

Required role: archive-content-manager

Response: 200 OK with a ReportConfigList, sorted by name.

Get a report configuration

GET /v2/report-configs/{configId}

Required role: archive-content-manager

Response: 200 OK with a ReportConfig.

• 404: there's no report configuration with this ID.

Create a report configuration

Sets up a report. If you set a schedule, the archive generates the report on that schedule from then on.

POST /v2/report-configs

Required role: archive-content-manager

{
  "name": "Packages created this month",
  "reportType": "packages_query",
  "outputFormat": "CSV",
  "schedule": "0 0 6 1 * ?",
  "criteria": {
    "combinator": "AND",
    "rules": [
      { "field": "dc:created", "operator": "IN_LAST", "value": "P1M" }
    ]
  },
  "reportFields": ["aip:packageId", "dc:title", "dc:created"]
}

Response: 200 OK with the ReportConfig.

• 400 with REQUIRED_FIELD: query, criteria, or reportFields is missing for a report type that needs it.

• 400 with INVALID_JSON: query isn't valid JSON.

• 400 with INVALID_VALUE: query is valid JSON, but not the shape that the report type needs.

• 400 with INVALID_CRON: schedule isn't a valid cron expression.

• 400: the criteria or reportFields aren't valid. The reason says which rule.

Update a report configuration

Replaces the configuration with the body that you send. The body has the same fields as Create a report configuration, so send all of them.

PUT /v2/report-configs/{configId}

Required role: archive-content-manager

Response: 200 OK with the updated ReportConfig.

• 404: there's no report configuration with this ID.

• The 400 errors of Create a report configuration.

Delete a report configuration

DELETE /v2/report-configs/{configId}

Required role: archive-content-manager

Response: 204 No Content. The reports that the configuration already generated stay available.

• 404: there's no report configuration with this ID.

Run a report now

Generates a report from the configuration straight away, outside its schedule. The call waits until the report is ready, so it can take a while for a large report.

POST /v2/report-configs/{configId}/run

Required role: archive-content-manager

Response: 200 OK with the Report that the archive generated, with trigger set to INSTANT. To download it, get the report by its id with Get a report.

• 400 with INVALID_REQUEST: the archive couldn't run the report's query. The message says why.

• 403: you don't have the rights to run this report.

• 404: there's no report configuration with this ID.

List reports

Returns the reports that the archive generated, newest first.

GET /v2/reports

Required role: none. You need archive manager rights, which come with the archive-content-manager role. Without them, the list is empty.

Response: 200 OK with a ReportList.

Get a report

Returns one report, with the link to download its file.

GET /v2/reports/{reportId}

Required role: none. You need the same rights as for the list. Without them, you get a 404.

Response: 200 OK with a Report.

{
  "id": "0b8e5f3a-2c41-4d6e-8f7a-91b2c3d4e5f6",
  "name": "Packages created this month-CSV-2026-10-01T06:00:02.418Z.csv",
  "reportConfig": "Packages created this month",
  "format": "CSV",
  "trigger": "SCHEDULED",
  "createdAt": "2026-10-01T06:00:02.418Z",
  "downloadUrl": "https://archive.example.com/v2/content/eyJhbGciOi..."
}

• 404: there's no report with this ID, or you don't have the rights to see it.

Download a report file

To download the file, send a GET request to the report's downloadUrl, with your usual Authorization and tenant headers. The link expires after 24 hours by default. To get a fresh link, get the report again.

curl -o report.csv "https://archive.example.com/v2/content/eyJhbGciOi..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: example-tenant"

• 410 with CONTENT_LINK_EXPIRED: the link has expired.

Schemas

ReportConfig

ReportConfigList

Report

ReportList