Skai (Kenshoo) Synchronous Reports API

openapi: 3.2.0
info:
  title: Skai Synchronous Reports API
  description: '# Overview

    Skai APIs provide programmatic access to advertising data and campaign management across Search, Social, and Retail Media publishers.'
  version: 1.0.0
  x-logo:
    url: https://grid.kenshoo.com/resources-frontend/latest/kenshoo_logo/skai-logo-devportal.svg
    backgroundColor: '#FFFFFF'
    altText: Skai
servers:
- url: https://services.kenshoo.com
security:
- BearerAuth: []
tags:
- name: Synchronous Reports
paths:
  /api/v1/reports:
    post:
      tags:
      - Synchronous Reports
      summary: Fetch a report
      description: 'Fetch reporting data for any entity type across all connected publisher accounts.


        **Supported entities:** `CAMPAIGN` `ADGROUP` `KEYWORD` `AD` `PRODUCT_ASSET` `PRODUCT_TARGETING` `PORTFOLIO`


        Less commonly used entities — `LOCATIONS`, `NEGATIVE_KEYWORDS`, `SITELINK`, `CREATIVE_ASSET`, `ASSET_GROUP` — are also supported. Use Available Columns with the relevant entity to retrieve their column lists.


        #### Building a request


        1. **Choose an `entity`** — the grid you want to report on (e.g. `CAMPAIGN`).

        2. **Pick your `fields`** — each field needs a `name` and a `group`. Use Available Columns to browse what''s available. The `group` value maps directly to the column group names returned by that endpoint (e.g. `ATTRIBUTES`, `PERFORMANCE`, `TimeSegment`).

        3. **Set a `date_range`** — `start_date` and `end_date` in `YYYY-MM-DD` format.

        4. **Add `profile_id` or `profile_token`** if you need single-profile columns (dimensions, custom metrics, conversion events). Use `profile_id=0` for cross-profile columns only.


        #### Pagination


        Results are limited to 1000 rows per request. Use `page` (0-indexed) to paginate through larger result sets. For datasets over a few thousand rows, prefer Async Analysis Reports — they stream results to a file with no row limit.


        #### Filtering and sorting


        Use `filters` to narrow rows before they''re returned (e.g. `Impressions > 0` to skip zero-spend rows). Use `sort` to order results server-side before pagination is applied.'
      operationId: fetchReport
      parameters:
      - $ref: '#/components/parameters/ks'
      requestBody:
        $ref: '#/components/requestBodies/ReportRequest'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportApiResponseDTO'
        400:
          $ref: '#/components/responses/BadRequest'
        500:
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    ks:
      name: ks
      in: query
      description: The KS to refer the request to. You can find this ID in the Skai platform under _Administration_ -> _About Skai_ -> _Server ID_
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: '1234'
  schemas:
    ReportSort:
      required:
      - field
      - group
      type: object
      properties:
        field:
          type: string
          description: The field to be sorted
        order:
          type: string
          enum:
          - ASCENDING
          - DESCENDING
          default: ASCENDING
        group:
          type: string
          description: Each column belongs to a group. This list is partial - your account may have additional column groups. Group names are available in the getAvailableColumns endpoint
          enum:
          - ATTRIBUTES
          - PERFORMANCE
          - DIMENSIONS
          - CUSTOM_METRICS
          - CUSTOM_METRICS_PLUS
          - CONVERSION_TYPES
          - CHANNEL_CUSTOMER_CONVERSION_TYPES
          - PROXY_CUSTOMER_CONVERSION_TYPES
          - EXTERNAL_CUSTOMER_CONVERSION_TYPES
      description: The properties of the sort
      example:
        field: CampaignId
        group: ATTRIBUTES
        order: DESCENDING
    ErrorField:
      type: object
      properties:
        fieldName:
          type: string
          description: The error field
        error:
          type: string
          description: Error message
        parameters:
          type: object
          additionalProperties:
            type: string
          description: Error additional properties
    Column:
      required:
      - group
      - name
      type: object
      properties:
        name:
          type: string
          description: Field name to be fetched
        group:
          type: string
          description: Each column belongs to a group. This list is partial - your account may have additional column groups. Group names are available in the getAvailableColumns endpoint
          enum:
          - Attributes
          - Performance
          - Dimensions
          - CustomMetrics
          - CustomMetricsPlus
          - ConversionTypes
          - ChannelCustomerConversionTypes
          - ProxyCustomerConversionTypes
          - ExternalCustomerConversionTypes
        id:
          type: string
          readOnly: true
        display_name:
          type: string
          readOnly: true
        value_type:
          type: string
          readOnly: true
          enum:
          - STRING
          - INTEGER
          - FLOAT
          - BOOLEAN
          - DATE
      description: The properties of a field
      example:
      - name: Clicks
        group: Performance
    ReportRecord:
      type: object
      properties:
        record_values:
          type: object
          additionalProperties:
            type: string
          readOnly: true
      example:
      - record_values:
          CampaignName:
          - group: ATTRIBUTES
            value: My Campaign
          Clicks:
          - group: PERFORMANCE
            value: '10'
      - record_values:
          CampaignName:
          - group: ATTRIBUTES
            value: New Campaign via API_UPDATED_TWICE
          Clicks:
          - group: PERFORMANCE
            value: '5'
    EntityResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
        success:
          type: boolean
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorField'
    ReportEntity:
      type: string
      description: The base entity for the report, indicated in the analysis grid name. Important - When using the API for product grids, refer to the entity as "PRODUCT_ASSET".
      enum:
      - CAMPAIGN
      - ADGROUP
      - KEYWORD
      - AD
      - PORTFOLIO
      - PRODUCT_ASSET
      - LOCATIONS
      - NEGATIVE_KEYWORDS
      - SITELINK
      - CREATIVE_ASSET
      - PRODUCT_TARGETING
      - ASSET_GROUP
    ReportApiResponseDTO:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ReportResponseStructure'
        error_message:
          type: string
          readOnly: true
    ReportResponseStructure:
      type: object
      properties:
        records:
          $ref: '#/components/schemas/ReportRecord'
        summary:
          $ref: '#/components/schemas/ReportRecordSummary'
        total:
          type: integer
          format: int64
          readOnly: true
    ReportFilter:
      required:
      - field
      - operator
      - values
      type: object
      properties:
        field:
          type: string
          description: Field name to be fetched
        operator:
          type: string
          enum:
          - EQUALS
          - NOT_EQUALS
          - IN
          - NOT_IN
          - GREATER_THAN
          - GREATER_THAN_EQUALS
          - LESS_THAN
          - LESS_THAN_EQUALS
          - STARTS_WITH
          - CONTAINS
          - DOES_NOT_CONTAIN
          - CONTAINS_ANY
          - CONTAINS_NONE
          - ENDS_WITH
          - IS_EMPTY
          - IS_NOT_EMPTY
          - BETWEEN
        values:
          type: array
          items:
            type: string
        group:
          type: string
          description: Each column belongs to a group. This list is partial - your account may have additional column groups. Group names are available in the getAvailableColumns endpoint
          enum:
          - ATTRIBUTES
          - PERFORMANCE
          - DIMENSIONS
          - CUSTOM_METRICS
          - CUSTOM_METRICS_PLUS
          - CONVERSION_TYPES
          - CHANNEL_CUSTOMER_CONVERSION_TYPES
          - PROXY_CUSTOMER_CONVERSION_TYPES
          - EXTERNAL_CUSTOMER_CONVERSION_TYPES
      description: Name of the field to which the condition will apply with certain values.
      example:
      - field: StatusToDisplay
        group: ATTRIBUTES
        operator: In
        values:
        - Approved
        - Active
      - field: CampaignName
        group: ATTRIBUTES
        operator: CONTAINS
        values:
        - New
      - field: Impressions
        group: PERFORMANCE
        operator: GREATER_THAN
        values:
        - '0'
    ReportRequest:
      required:
      - date_range
      - entity
      - fields
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/ReportEntity'
        date_range:
          $ref: '#/components/schemas/DateRange'
        fields:
          uniqueItems: true
          type: array
          description: 'The columns to be fetched. See [here](#operation/getAvailableColumns) for available columns.

            To get data segmented by date, add a date column, like so: `{"name": "Day", "group": "TimeSegment"}`'
          items:
            $ref: '#/components/schemas/Column'
        filters:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/ReportFilter'
        sort:
          $ref: '#/components/schemas/ReportSort'
        info_level:
          type: string
          description: Show summary records only, breakdown records only, or both.
          enum:
          - SUMMARY
          - BREAKDOWN
          - BOTH
          default: BOTH
        breakdown_type:
          type: string
          description: To get data segmented only by date, use `GROUP`. To segment by both date and another column, use `SEGMENT` with only the date column in group_bys and include the other column in `fields` (these columns will be fetched). Otherwise, use `FLAT`
          enum:
          - FLAT
          - GROUP
          - SEGMENT
          default: FLAT
        group_bys:
          type: Array
          description: When the breakdown type is "SEGMENT", select columns by which to group the data.
        profile_token:
          type: string
          description: Profile token. This is needed to access [Single-Profile columns](#operation/getAvailableColumns) (alternative to profile_id).
        profile_id:
          type: number
          description: Profile ID. This is needed to access [Single-Profile columns](#operation/getAvailableColumns) (alternative to profile_token).
        limit:
          maximum: 1000
          type: integer
          description: Set a limit for the retrieved records
          format: int32
          default: 1000
        page:
          type: integer
          description: The number of the report page you want to retrieve. You can use this together with the Limit parameter to define the number of records per page. The first page number is 0.
          format: int32
          default: 0
      description: The properties for the report request
      example:
        entity: CAMPAIGN
        profile_id: 118
        date_range:
          start_date: '2026-01-01'
          end_date: '2026-01-14'
        fields:
        - name: CampaignName
          group: ATTRIBUTES
        - name: Clicks
          group: PERFORMANCE
        filters:
        - field: StatusToDisplay
          group: ATTRIBUTES
          operator: In
          values:
          - Approved
          - Active
        - field: CampaignName
          group: ATTRIBUTES
          operator: CONTAINS
          values:
          - My
        - field: Impressions
          group: PERFORMANCE
          operator: GREATER_THAN
          values:
          - '0'
        breakdown_type: GROUP
        sort:
          field: CampaignName
          group: ATTRIBUTES
          order: DESCENDING
        limit: 1000
        page: 0
    ApiResponseStatus:
      type: string
      readOnly: true
      enum:
      - SUCCESS
      - FAILED
      - PARTIAL_SUCCESS
    DateRange:
      required:
      - end_date
      - start_date
      type: object
      properties:
        start_date:
          type: string
          description: Start date in YYYY-MM-dd format
        end_date:
          type: string
          description: End date in YYYY-MM-dd format
        exclude_dates:
          type: array
          items:
            type: string
            description: Dates to exclude in YYYY-MM-dd format
            readOnly: true
      description: The properties of the date range.
      example:
      - start_date: '2026-01-01'
        end_date: '2026-01-14'
        exclude_dates:
        - '2026-01-07'
    ApiResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiResponseStatus'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/EntityResponse'
    ReportRecordSummary:
      type: object
      properties:
        record_values:
          type: object
          additionalProperties:
            type: string
          readOnly: true
      example:
        record_values:
          CampaignName:
          - group: ATTRIBUTES
            value: ''
          Clicks:
          - group: PERFORMANCE
            value: '15'
  responses:
    BadRequest:
      description: Bad request (usually indicates validation failure for client input)
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: name
                error: ILLEGAL_NAME
    ApiResponse:
      $ref: '#/components/schemas/ApiResponse'
    InternalServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/responses/ApiResponse'
          example:
            status: FAILED
            entities:
            - id: null
              success: false
              errors:
              - field_name: ServerError
                error: Unexpected error occurred.
                parameters: {}
  requestBodies:
    ReportRequest:
      description: The report request to create
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReportRequest'
      required: true
x-tagGroups:
- name: Reporting
  tags:
  - Available Columns
  - Synchronous Reports
  - Asynchronous Reports
- name: Bulk Operations
  tags:
  - Jobs
  - Bulk Update
- name: AI & MCP
  tags:
  - MCP
- name: Objects
  tags:
  - Profile
  - Campaigns
  - Ad Groups
  - Ads
  - Product Groups
  - Portfolios
  - Meta Campaigns
  - Meta Ad Groups
  - Meta Ads
  - Columns