List report history


Use this endpoint to get details about scheduled reports and individual report runs.

Example requests and responses

curl --request GET '' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
200 OK
    "page": {
        "total": 1,
        "limit": 1,
        "offset": 0
    "report_history": [
            "report_display_name": "Example Report",
            "report_identifier": "00000000-0000-0000-0000-000000000000",
            "report_run_identifier": "11111111-1111-1111-1111-11111111",
            "created_by_user_id": 12345,
            "created_by_user_name": "John Doe",
            "created_date": "2021-01-13 02:15:48",
            "report_type": "orders",
            "report_type_display_name": "Orders",
            "report_start_date": "2021-01-13 09:15:37",
            "report_end_date": "2021-01-13 09:15:48",
            "schedule": "WEEKLY", 
            "format": [
            "status": "READY",
            "manually_triggered": false,
            "split_report_count": 0

URL query parameters

You can filter, sort, and paginate the results for this endpoint by using URL query strings.

To use multiple filters, append the query string for each filter to your request. For example, the filters in this request limit the results to order reports that run on a monthly schedule:


To create a filter that accepts multiple values, provide a comma-separated list of each value that meets your filter criteria. For example, the filters in this request limit the results to reports with:

  • A display name of test or example.
  • A status of FAILED or READY.
Name Req/Opt Type Description
offset optional integer Zero-based offset index for the first record to include in the response. Must be greater than or equal to 0.
Default: 0
limit optional integer Number of records to include in the response. Must be a positive integer.
Default: 100
report_display_name optional string Filters results by report display name.
schedule optional string Filters results by report schedule.
Possible values: ON_DEMAND, WEEKLY, and MONTHLY.
status optional string Filters results by report status.
Possible values:
  • SCHEDULED - Report is active.
  • GENERATING - Report run is in progress.
  • READY - Report run is complete and the results are ready for download.
  • FAILED - Report run failed.
report_type optional string Filters results by report type.
Possible values: See List report types
search optional string Searches reports by display name. The response includes reports with a report_display_name value that is an exact or partial match to the searched value.

For example, searching for the string example returns reports with any of these display names: example_test, test_example, or example on its own.
sort_by optional string Parameter by which to sort results.
Possible values:
  • report_display_name
  • report_type
  • schedule
  • format
Default: report_start_date.
sort_direction optional string Sort direction. Use ASC (0-9, A-Z) or DESC (9-0, Z-A).
Default: ASC, unless both sort_by and sort_direction are empty. In this case, results are sorted in DESC order by report_start_date (the default sort_by parameter).
language_id optional int ID of the language to use for the string returned in the report_type_display_name field.
Allowed values: See Glossary - Locale codes
Default: English (1)

Response parameters

Name Type Description
page object Object with pagination details.
.. total integer Total number of reports.
.. limit integer Number of reports in the results.
.. offset integer Zero-based offset index of the first record in the results.
report_history array of objects List of objects. Each object contains details for a scheduled report or an individual report run.
.. report_display_name string Report display name.
.. report_identifier string Report ID (UUID).
.. report_run_identifier string Report run ID (UUID). An empty string indicates that the object represents a scheduled report instead of an individual report run.
.. created_by_user_id string ID of the user that created the report.
.. created_date string Report creation date and timestamp in UTC.
Format: YYYY-MM-DD hh:mm:ss
.. created_by_user_name string Username of the user that created the report.
.. report_type string Report type.
Possible values: See List report types .
.. report_type_display_name string Report type display name. To get this value in a language other than English, use the language_id query parameter.
.. report_start_date date For individual report runs, the date and time (UTC) the report run started. For scheduled reports, the starting date and time of the next report run.
Format: YYYY-MM-DD hh:mm:ss
.. report_end_date date Date and time (UTC) the report run finished. Only returned for completed report runs (status = READY).
Format: YYYY-MM-DD hh:mm:ss
.. schedule string The frequency of report creation.
Possible values: ON_DEMAND, WEEKLY, and MONTHLY.
.. format array of strings List of filetype formats in which you can download the results of a report run.
.. status string The status of the report.
.. manually_triggered boolean If true, a user initiated this report run manually by submitting an API request or using the CertCentral console. Otherwise, the report library service initiated the report run automatically, in accordance with the report's schedule.
.. split_report_count integer Number of files the report run is split into. For report runs that do not exceed the maximum number of rows per file, returns 0.