Retrieve a list of reports - Ortto Knowledge Base

Overview

The list Ortto endpoint of the reports entity is used to retrieve a list of reports within Ortto’s customer data platform (CDP).

NOTE: You can also retrieve one report by referring to the v1/reports/get endpoint in retrieve one report (get).

This page provides descriptions of this endpoint's:

Request resource and method.
Valid parameters, headers and request body values.
The response payload.

HTTP method and request resource


 POST https://api.ap3api.com/v1/reports/list

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object whose valid elements are listed in the table below.

Example get reports list request body from Ortto's CDP.

json
 {
  "search_term": "",
  "limit": 3
}

Valid request body elements

The following table lists all valid, optional request body elements that are available at this endpoint.

Element	Type	Description
`state`	`string`	The state is for choosing to filter on the type with the following: Dynamic reports: `state` = "live" Snapshot reports: `state` = "snapshot"
`chart_type`	`string`	The type the report is created as, e.g. table, pie-chart, metric).
`search_term`	`string`	The term used to search for report names.
`folder_id`	`string`	The `folder_id` element is the ID of the folder your report is in.
`linked_state`	`string`	If the report is used in a dashboard. `linked`: this will return only reports used in a dashboard. `unlinked`: this will return reports that aren't used in a dashboard.
`sort_order`	`string` with value `asc` or `desc` (default value is `desc`)	The `sort_order` element determines the order in which the reports returned are sorted, based on the `sort` element. Specifying this `sort_order` member is only relevant when the `sort` element is also specified.
`sort`	`string`	The `sort` element is used to specify the report field used to sort the reports returned from your Ortto account’s CDP. For example, this includes `name` (for report name), `type`, `last_edited`

Response payload

The following JSON object is an example of a report list call that Ortto retrieves from your Ortto account's CDP after a request to this endpoint.

json
 {
  "reports": [
    {
      "id": "630c302b6b42a00cea949e7d",
      "instance_id": "professionalpete",
      "type": "dynamic",
      "object_type": "contact",
      "chart_type": "table",
      "image_url": null,
      "created_by_id": "628ab642c6fc743e4750e289",
      "created_by_name": "",
      "created_at": "2022-08-29T03:19:07.91Z",
      "last_edited": "2025-11-25T05:15:50.063Z",
      "edited_by_id": "628ab642c6fc743e4750e289",
      "edited_by_name": "Joe Doyle",
      "last_refreshed": "0001-01-01T00:00:00Z",
      "name": "Campaign summary",
      "time_precision": "days",
      "conversion_window": "entire-range",
      "timezone": "Australia/Sydney",
      "timeframe": {
        "type": "last-year",
        "custom_from": {
          "year": 0,
          "month": 0,
          "day": 0,
          "timezone": "UTC"
        },
        "custom_to": {
          "year": 0,
          "month": 0,
          "day": 0,
          "timezone": "UTC"
        }
      },
      "number_display_type": "",
      "refresh_rate": "",
      "display_values": false,
      "trendline": false,
      "stack_values": false,
      "is_cumulative": false,
      "suppression_filter": false,
      "previous_period": false,
      "associated_by_attribute_id": "",
      "table_group_by_attribute_id": "",
      "table_group_by_label": "",
      "table_group_by_display_type": "",
      "table_group_by_precision": "",
      "is_table_group_by_contact_field": false,
      "group_empty_as_unknown": false,
      "sort": "",
      "pie_results": 10,
      "activities": [
        {
          "selected_attributes": [
            {
              "id": "tme::time",
              "title": "Time",
              "name": "Time",
              "display_type": "timestring",
              "special": "time",
              "precision": "days",
              "format": "MM:DD"
            }
          ],
          "field_id": "act::r",
          "title": "Received email",
          "label": "Received",
          "icon": "",
          "aggregate_by_attribute_id": "",
          "aggregate_by_attribute_type": "",
          "associated_by_attribute_id": "",
          "group_by_attribute_id": "",
          "group_by_attribute_type": "",
          "is_group_by_contact_field": false,
          "is_unique_by_group_by": false,
          "aggregate_operation": "count",
          "ratio_with_activity_display_type": "percent",
          "ratio_with_activity_id": "",
          "ratio_aggregate_by_attribute_id": "",
          "ratio_aggregate_by_attribute_type": "",
          "ratio_associated_by_attribute_id": "",
          "ratio_aggregate_operation": "count",
          "nps_show_response_values": false
        },
        {
          "selected_attributes": [
            {
              "id": "tme::time",
              "title": "Time",
              "name": "Time",
              "display_type": "timestring",
              "special": "time",
              "precision": "days",
              "format": "MM:DD"
            }
          ],
          "field_id": "act::o",
          "title": "Opened email",
          "label": "Open rate",
          "icon": "",
          "aggregate_by_attribute_id": "",
          "aggregate_by_attribute_type": "",
          "associated_by_attribute_id": "idt::ei",
          "group_by_attribute_id": "",
          "group_by_attribute_type": "",
          "is_group_by_contact_field": false,
          "is_unique_by_group_by": false,
          "aggregate_operation": "count-unique",
          "ratio_with_activity_display_type": "percent",
          "ratio_with_activity_id": "act::r",
          "ratio_aggregate_by_attribute_id": "",
          "ratio_aggregate_by_attribute_type": "",
          "ratio_associated_by_attribute_id": "idt::ei",
          "ratio_aggregate_operation": "count-unique",
          "nps_show_response_values": false
        },
        {
          "selected_attributes": [
            {
              "id": "tme::time",
              "title": "Time",
              "name": "Time",
              "display_type": "timestring",
              "special": "time",
              "precision": "days",
              "format": "MM:DD"
            }
          ],
          "field_id": "act::c",
          "title": "Clicked email",
          "label": "Click rate",
          "icon": "",
          "aggregate_by_attribute_id": "",
          "aggregate_by_attribute_type": "",
          "associated_by_attribute_id": "idt::ei",
          "group_by_attribute_id": "",
          "group_by_attribute_type": "",
          "is_group_by_contact_field": false,
          "is_unique_by_group_by": false,
          "aggregate_operation": "count-unique",
          "ratio_with_activity_display_type": "percent",
          "ratio_with_activity_id": "act::r",
          "ratio_aggregate_by_attribute_id": "",
          "ratio_aggregate_by_attribute_type": "",
          "ratio_associated_by_attribute_id": "idt::ei",
          "ratio_aggregate_operation": "count-unique",
          "nps_show_response_values": false
        },
        {
          "selected_attributes": [
            {
              "id": "tme::time",
              "title": "Time",
              "name": "Time",
              "display_type": "timestring",
              "special": "time",
              "precision": "days",
              "format": "MM:DD"
            }
          ],
          "field_id": "act::rt",
          "title": "Reacted to email",
          "label": "Reactions",
          "icon": "",
          "aggregate_by_attribute_id": "",
          "aggregate_by_attribute_type": "",
          "associated_by_attribute_id": "",
          "group_by_attribute_id": "",
          "group_by_attribute_type": "",
          "is_group_by_contact_field": false,
          "is_unique_by_group_by": false,
          "aggregate_operation": "count",
          "ratio_with_activity_display_type": "percent",
          "ratio_with_activity_id": "",
          "ratio_aggregate_by_attribute_id": "",
          "ratio_aggregate_by_attribute_type": "",
          "ratio_associated_by_attribute_id": "",
          "ratio_aggregate_operation": "count",
          "nps_show_response_values": false
        },
        {
          "selected_attributes": [
            {
              "id": "tme::time",
              "title": "Time",
              "name": "Time",
              "display_type": "timestring",
              "special": "time",
              "precision": "days",
              "format": "MM:DD"
            }
          ],
          "field_id": "act::b",
          "title": "Bounced email",
          "label": "Bounced email",
          "icon": "bounced-icon",
          "aggregate_by_attribute_id": "",
          "aggregate_by_attribute_type": "",
          "associated_by_attribute_id": "",
          "group_by_attribute_id": "",
          "group_by_attribute_type": "",
          "is_group_by_contact_field": false,
          "is_unique_by_group_by": false,
          "aggregate_operation": "count",
          "ratio_with_activity_display_type": "percent",
          "ratio_with_activity_id": "",
          "ratio_aggregate_by_attribute_id": "",
          "ratio_aggregate_by_attribute_type": "",
          "ratio_associated_by_attribute_id": "",
          "ratio_aggregate_operation": "count",
          "nps_show_response_values": false
        }
      ],
      "data_change_on_sort": false
    }
    …
  ],
  "meta": {
    "total_reports": 74,
    "total_active_reports": 74
  },
  "offset": 0,
  "next_offset": 3,
  "has_more": true,
  "folder_id": "000000000000000000000000"
}