> ## Documentation Index
> Fetch the complete documentation index at: https://doc.extole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a report

> Submits a new report run for the specified report type and parameters. The report executes asynchronously; poll the returned report ID to check status.



## OpenAPI

````yaml /api-reference/management.json post /v4/reports
openapi: 3.0.1
info:
  description: >-
    Configuration endpoints for the Extole platform: campaigns, components,
    audiences, persons, rewards, reporting, integrations setup, and
    administrative tooling.
  title: Management API
  version: '1.0'
servers:
  - description: Production
    url: https://api.extole.io
security:
  - HEADER: []
  - QUERY: []
  - COOKIE: []
tags:
  - name: Audiences
  - name: Authentication
  - name: Batch Jobs
  - name: Blocks
  - name: Campaigns
  - name: Components
  - name: Components Settings
  - name: Domains
  - name: Email
  - name: Erasure
  - name: Event Streams
  - name: File Validation Monitors
  - name: Optout
  - name: Profiles
  - name: Promotion Links
  - name: Report Schedules
  - name: Report Types
  - name: Reports
  - name: Reward Suppliers
  - name: Security Keys
  - name: Settings
  - name: User Notifications
  - name: User Subscriptions
  - name: Users
  - name: Webhooks
paths:
  /v4/reports:
    post:
      tags:
        - Reports
      summary: Create a report
      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
components:
  schemas:
    CreateReportRequest:
      properties:
        display_name:
          nullable: true
          type: string
        format:
          enum:
            - CSV
            - HEADLESS_CSV
            - HEADLESS_PSV
            - JSON
            - JSONL
            - PSV
            - XLSX
          nullable: true
          type: string
        formats:
          items:
            enum:
              - CSV
              - HEADLESS_CSV
              - HEADLESS_PSV
              - JSON
              - JSONL
              - PSV
              - XLSX
            type: string
          nullable: true
          type: array
        name:
          type: string
        parameters:
          additionalProperties:
            type: string
          type: object
        report_type:
          type: string
        rerun:
          nullable: true
          type: boolean
        scopes:
          items:
            enum:
              - CLIENT_ADMIN
              - CLIENT_SUPERUSER
              - CONSUMER_PUBLIC
            type: string
          nullable: true
          type: array
          uniqueItems: true
        sftp_report_name:
          nullable: true
          type: string
        sftp_server_id:
          nullable: true
          type: string
        tags:
          items:
            type: string
          nullable: true
          type: array
          uniqueItems: true
      required:
        - display_name
        - format
        - formats
        - name
        - parameters
        - report_type
        - rerun
        - scopes
        - sftp_report_name
        - sftp_server_id
        - tags
      type: object
    ReportResponse:
      properties:
        completed_date:
          nullable: true
          type: string
        display_name:
          type: string
        download_uri:
          nullable: true
          type: string
        formats:
          items:
            enum:
              - CSV
              - HEADLESS_CSV
              - HEADLESS_PSV
              - JSON
              - JSONL
              - PSV
              - XLSX
            type: string
          type: array
        name:
          type: string
        report_id:
          type: string
        report_type:
          type: string
        tags:
          items:
            type: string
          type: array
          uniqueItems: true
      required:
        - completed_date
        - display_name
        - download_uri
        - formats
        - name
        - report_id
        - report_type
        - tags
      type: object
    RestExceptionResponse:
      description: Represents the API error response
      properties:
        code:
          description: Specific error code for this error type, documented per endpoint
          type: string
        http_status_code:
          description: >-
            HTTP status code that was returned with this error, useful if client
            get response code
          format: int32
          type: integer
        message:
          description: User readable English description of the error
          type: string
        parameters:
          additionalProperties:
            description: >-
              Attributes related to the error, varies be error code, documented
              per endpoint
            type: object
          description: >-
            Attributes related to the error, varies be error code, documented
            per endpoint
          type: object
        unique_id:
          description: >-
            Unique id associated with this error, useful for discussions with
            Extole
          type: string
      required:
        - code
        - http_status_code
        - message
        - parameters
        - unique_id
      type: object
  examples:
    binding_error:
      summary: binding_error
      value:
        code: binding_error
        http_status_code: 400
        message: Argument is not of the expected type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_json:
      summary: invalid_json
      value:
        code: invalid_json
        http_status_code: 400
        message: JSON is invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_parameter:
      summary: invalid_parameter
      value:
        code: invalid_parameter
        http_status_code: 400
        message: Parameter is invalid.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_request_body:
      summary: missing_request_body
      value:
        code: missing_request_body
        http_status_code: 400
        message: Missing request body
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_display_name_empty:
      summary: report_display_name_empty
      value:
        code: report_display_name_empty
        http_status_code: 400
        message: Report display name is empty
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_display_name_too_long:
      summary: report_display_name_too_long
      value:
        code: report_display_name_too_long
        http_status_code: 400
        message: Report display name is too long
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_invalid_formats:
      summary: report_invalid_formats
      value:
        code: report_invalid_formats
        http_status_code: 400
        message: Report formats not supported
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_invalid_operation:
      summary: report_invalid_operation
      value:
        code: report_invalid_operation
        http_status_code: 400
        message: Current report state doesn't allow the specified operation
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_invalid_parameter:
      summary: report_invalid_parameter
      value:
        code: report_invalid_parameter
        http_status_code: 400
        message: Report parameter(s) of invalid format
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_invalid_scopes:
      summary: report_invalid_scopes
      value:
        code: report_invalid_scopes
        http_status_code: 400
        message: Report scopes invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_invalid_sftp_server:
      summary: report_invalid_sftp_server
      value:
        code: report_invalid_sftp_server
        http_status_code: 400
        message: Invalid SFTP server
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_missing_aggregation_parameter:
      summary: report_missing_aggregation_parameter
      value:
        code: report_missing_aggregation_parameter
        http_status_code: 400
        message: Report must have at least one aggregating function
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_missing_parameters:
      summary: report_missing_parameters
      value:
        code: report_missing_parameters
        http_status_code: 400
        message: Report is missing parameters
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_name_illegal_character:
      summary: report_name_illegal_character
      value:
        code: report_name_illegal_character
        http_status_code: 400
        message: >-
          Report name can only contain alphanumeric, space, dash, parenthesis,
          slash, colon, comma, period, underscore, dollar and percentage
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_tags_too_long:
      summary: report_tags_too_long
      value:
        code: report_tags_too_long
        http_status_code: 400
        message: Tags are too long
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_type_missing:
      summary: report_type_missing
      value:
        code: report_type_missing
        http_status_code: 400
        message: Report type is missing
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_type_not_found:
      summary: report_type_not_found
      value:
        code: report_type_not_found
        http_status_code: 400
        message: Report type referenced by the component is not found
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    report_update_invalid:
      summary: report_update_invalid
      value:
        code: report_update_invalid
        http_status_code: 400
        message: Report update invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    method_unauthorized:
      summary: method_unauthorized
      value:
        code: method_unauthorized
        http_status_code: 401
        message: Unauthorized access to this endpoint
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    payment_required:
      summary: payment_required
      value:
        code: payment_required
        http_status_code: 402
        message: The access_token provided is associated with an unpaid account.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    access_denied:
      summary: access_denied
      value:
        code: access_denied
        http_status_code: 403
        message: >-
          The access_token provided is not permitted to access the specified
          resource.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_access_token:
      summary: missing_access_token
      value:
        code: missing_access_token
        http_status_code: 403
        message: No access_token was provided with this request.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    unsupported_media_type:
      summary: unsupported_media_type
      value:
        code: unsupported_media_type
        http_status_code: 415
        message: Request had an unsupported or no media type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    too_many_requests:
      summary: too_many_requests
      value:
        code: too_many_requests
        http_status_code: 429
        message: >-
          The server is unable to process your request at the moment, please
          retry later.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
  securitySchemes:
    HEADER:
      in: header
      name: Authorization
      type: apiKey
      x-bearer-format: bearer
    QUERY:
      in: query
      name: access_token
      type: apiKey
    COOKIE:
      in: cookie
      name: extole_token
      type: apiKey

````