Extole

Extole Reports API

The Reports API from Extole — 14 operation(s) for reports.

GitHub OpenAPI

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-reports-api-openapi.yml

OpenAPI Specification

extole-reports-api-openapi.yml Raw ↑ 
openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences Reports API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Reports
paths:
  /v4/reports:
    get:
      description: Returns all report runs visible to the authenticated client, optionally filtered by the provided query parameters.
      operationId: listReports
      parameters:
      - in: query
        name: report_type_name
        schema:
          type: string
      - in: query
        name: display_name
        schema:
          type: string
      - in: query
        name: status
        schema:
          items:
            enum:
            - CANCELED
            - DONE
            - EXPIRED
            - FAILED
            - IN_PROGRESS
            - PENDING
            - PENDING_DATA
            - SFTP_DELIVERY_FAILED
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: user_ids
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: having_any_tags
        schema:
          type: string
      - in: query
        name: having_all_tags
        schema:
          type: string
      - in: query
        name: exclude_having_any_tags
        schema:
          type: string
      - in: query
        name: exclude_having_all_tags
        schema:
          type: string
      - in: query
        name: search_query
        schema:
          type: string
      - in: query
        name: creation_interval
        schema:
          type: string
      - in: query
        name: offset
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: string
      - in: query
        name: order_by
        schema:
          enum:
          - DATE_COMPLETED
          - DATE_RUN
          - NAME
          - STATUS
          - USER
          type: string
      - in: query
        name: order
        schema:
          enum:
          - ASCENDING
          - DESCENDING
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ReportResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_timerange_format:
                  $ref: '#/components/examples/invalid_timerange_format'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List reports
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Submits a new report run for the specified report type and parameters. The report executes asynchronously; poll the returned report ID to check status.
      operationId: createReport
      requestBody:
        content:
          application/json:
            example:
              display_name: display_name
              format: CSV
              formats:
              - CSV
              name: name
              parameters:
                parameters_key: parameters_key
              report_type: report_type
              rerun: true
              scopes:
              - CLIENT_ADMIN
              sftp_report_name: sftp_report_name
              sftp_server_id: sftp_server_id
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/CreateReportRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                report_display_name_empty:
                  $ref: '#/components/examples/report_display_name_empty'
                report_display_name_too_long:
                  $ref: '#/components/examples/report_display_name_too_long'
                report_invalid_formats:
                  $ref: '#/components/examples/report_invalid_formats'
                report_invalid_operation:
                  $ref: '#/components/examples/report_invalid_operation'
                report_invalid_parameter:
                  $ref: '#/components/examples/report_invalid_parameter'
                report_invalid_scopes:
                  $ref: '#/components/examples/report_invalid_scopes'
                report_invalid_sftp_server:
                  $ref: '#/components/examples/report_invalid_sftp_server'
                report_missing_aggregation_parameter:
                  $ref: '#/components/examples/report_missing_aggregation_parameter'
                report_missing_parameters:
                  $ref: '#/components/examples/report_missing_parameters'
                report_name_illegal_character:
                  $ref: '#/components/examples/report_name_illegal_character'
                report_tags_too_long:
                  $ref: '#/components/examples/report_tags_too_long'
                report_type_missing:
                  $ref: '#/components/examples/report_type_missing'
                report_type_not_found:
                  $ref: '#/components/examples/report_type_not_found'
                report_update_invalid:
                  $ref: '#/components/examples/report_update_invalid'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create a report
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
  /v4/reports-tags:
    get:
      description: Returns the list of tags available for filtering reports.
      operationId: listReportTags
      parameters:
      - in: query
        name: having_any_tags
        schema:
          type: string
      - in: query
        name: exclude_having_any_tags
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List report tags
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
  /v4/reports/latest:
    get:
      description: Returns the most recent completed report run matching the specified report name and optional parameter filters.
      operationId: getLatestReport
      parameters:
      - in: query
        name: having_any_tags
        schema:
          type: string
      - in: query
        name: having_all_tags
        schema:
          type: string
      - in: query
        name: exclude_having_any_tags
        schema:
          type: string
      - in: query
        name: exclude_having_all_tags
        schema:
          type: string
      - in: query
        name: order_by
        schema:
          enum:
          - DATE_COMPLETED
          - DATE_RUN
          - NAME
          - STATUS
          - USER
          type: string
      - in: query
        name: order
        schema:
          enum:
          - ASCENDING
          - DESCENDING
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                report_content_by_tags_not_found:
                  $ref: '#/components/examples/report_content_by_tags_not_found'
                report_content_format_by_tags_not_found:
                  $ref: '#/components/examples/report_content_format_by_tags_not_found'
                report_content_format_not_found:
                  $ref: '#/components/examples/report_content_format_not_found'
                report_content_not_found:
                  $ref: '#/components/examples/report_content_not_found'
                report_content_not_supported:
                  $ref: '#/components/examples/report_content_not_supported'
                report_filter_missing:
                  $ref: '#/components/examples/report_filter_missing'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get the latest report
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
  /v4/reports/latest/download{format}:
    get:
      description: Downloads the output of the most recent completed report run matching the specified report name and optional filters. Append a format extension to select the download format.
      operationId: downloadLatestReport
      parameters:
      - in: header
        name: Content-Type
        schema:
          type: string
      - in: path
        name: format
        required: true
        schema:
          nullable: true
          pattern: (\.csv|\.json|\.jsonl|\.xlsx|\.psv|\.headless_csv|\.headless_psv)?
          type: string
      - in: query
        name: having_any_tags
        schema:
          type: string
      - in: query
        name: having_all_tags
        schema:
          type: string
      - in: query
        name: exclude_having_any_tags
        schema:
          type: string
      - in: query
        name: exclude_having_all_tags
        schema:
          type: string
      - in: query
        name: order_by
        schema:
          enum:
          - DATE_COMPLETED
          - DATE_RUN
          - NAME
          - STATUS
          - USER
          type: string
      - in: query
        name: order
        schema:
          enum:
          - ASCENDING
          - DESCENDING
          type: string
      - in: query
        name: offset
        schema:
          type: string
      - in: query
        name: limit
        schema:
          type: string
      - in: query
        name: filename
        schema:
          type: string
      responses:
        '200':
          content:
            '*/*': {}
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                report_content_by_tags_not_found:
                  $ref: '#/components/examples/report_content_by_tags_not_found'
                report_content_format_by_tags_not_found:
                  $ref: '#/components/examples/report_content_format_by_tags_not_found'
                report_content_format_not_found:
                  $ref: '#/components/examples/report_content_format_not_found'
                report_content_not_found:
                  $ref: '#/components/examples/report_content_not_found'
                report_content_not_supported:
                  $ref: '#/components/examples/report_content_not_supported'
                report_filter_missing:
                  $ref: '#/components/examples/report_filter_missing'
                report_not_found:
                  $ref: '#/components/examples/report_not_found'
                report_preview_not_available:
                  $ref: '#/components/examples/report_preview_not_available'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Download the latest report
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
  /v4/reports/recommendations:
    get:
      description: Returns reports recommended for scheduling according to the selected recommendation type.
      operationId: listReportRecommendations
      parameters:
      - description: 'Recommendation type, can be one of: SCHEDULE'
        in: query
        name: type
        schema:
          enum:
          - SCHEDULE
          type: string
      - description: Optional filter for limit, defaults to 4.
        in: query
        name: limit
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ReportResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_limit:
                  $ref: '#/components/examples/invalid_limit'
                invalid_offset:
                  $ref: '#/components/examples/invalid_offset'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                max_fetch_size_1000:
                  $ref: '#/components/examples/max_fetch_size_1000'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List report recommendations
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
  /v4/reports/{reportId}:
    get:
      description: Returns the status and metadata for the report run identified by its report ID.
      operationId: getReport
      parameters:
      - in: path
        name: reportId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                report_not_found:
                  $ref: '#/components/examples/report_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get a report
      tags:
      - Reports
      x-extole-bundle: management
      x-extole-visibility: visible
    put:
      description: Updates the parameters of a pending report run identified by its report ID.
      operationId: updateReport
      parameters:
      - in: path
        name: reportId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              display_name: display_name
              scopes:
              - CLIENT_ADMIN
              tags:
              - tag
              visible: true
            schema:
              $ref: '#/components/schemas/UpdateReportRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                report_display_name_empty:
                  $ref: '#/components/examples/report_display_name_empty'
                report_display_name_too_long:
                  $ref: '#/components/examples/report_display_name_too_long'
                report_invalid_formats:
                  $ref: '#/components/examples/report_invalid_formats'
                report_invalid_operation:
                  $ref: '#/components/examples/report_invalid_operation'
                report_invalid_parameter:
                  $ref: '#/components/examples/report_invalid_parameter'
      

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-reports-api-openapi.yml