Metricool Performance Dashboard Insights API

openapi: 3.2.0
info:
  title: Metricool Performance Dashboard Insights API
  description: 'Metricool API


    The base URL for all endpoints is: https://app.metricool.com/api


    All endpoints require authentication.'
  version: 2.0.0
servers:
- url: https://app.metricool.com/api
tags:
- name: Performance Dashboard Insights
paths:
  /v2/reporting/campaigns-dashboard/{dashboardId}/insights:
    get:
      tags:
      - Performance Dashboard Insights
      summary: Get the latest AI insights for a campaign dashboard
      operationId: getDashboardInsights
      parameters:
      - name: dashboardId
        in: path
        description: Dashboard id
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponsePerformanceDashboardInsightsResponseDto'
    put:
      tags:
      - Performance Dashboard Insights
      summary: Edit (overwrite) one AI insights section of a campaign dashboard
      operationId: editInsightSection
      parameters:
      - name: dashboardId
        in: path
        description: Dashboard id
        required: true
        schema:
          type: integer
          format: int64
      - name: section
        in: query
        description: Section id, e.g. instagram, googleAds
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInsightSectionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponsePerformanceDashboardInsightsResponseDto'
  /v2/reporting/campaigns-dashboard/{dashboardId}/insights/regenerate:
    post:
      tags:
      - Performance Dashboard Insights
      summary: Regenerate one AI insights section of a campaign dashboard
      operationId: regenerateInsightSection
      parameters:
      - name: dashboardId
        in: path
        description: Dashboard id
        required: true
        schema:
          type: integer
          format: int64
      - name: section
        in: query
        description: Section id, e.g. instagram, googleAds
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
components:
  schemas:
    InsightSectionDto:
      required:
      - content
      - generationStatus
      type: object
      properties:
        generationStatus:
          type: string
          description: 'Per-section status: GENERATED, MODIFIED or PROCESSING'
        content:
          type: array
          description: Ordered boxes of the section
          items:
            $ref: '#/components/schemas/InsightBlockDto'
      description: Global best-posts section (null if absent)
    JsonOkResponsePerformanceDashboardInsightsResponseDto:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/PerformanceDashboardInsightsResponseDto'
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    UpdateInsightSectionRequest:
      required:
      - content
      type: object
      properties:
        content:
          maxItems: 4
          minItems: 0
          type: array
          description: Ordered boxes of the section (0 to 4). An empty list clears the section.
          items:
            $ref: '#/components/schemas/InsightBlockDto'
      description: Full replacement content for one insights section.
    DateTimeInfo:
      required:
      - dateTime
      type: object
      properties:
        dateTime:
          type: string
          description: 'Local Date-time represented with a certain timezone '
        timezone:
          type: string
          description: Timezone applied to the datetime
    InsightBlockDto:
      required:
      - text
      type: object
      properties:
        text:
          maxLength: 5000
          minLength: 0
          type: string
          description: Rich-text content of the box
      description: Ordered boxes of the section
    PerformanceDashboardInsightsResponseDto:
      required:
      - dashboardId
      - status
      type: object
      properties:
        dashboardId:
          type: integer
          description: Dashboard id
          format: int64
        status:
          type: string
          description: 'Job status: COMPLETED, GENERATING, FAILED, or NOT_GENERATED_YET'
        startedAt:
          $ref: '#/components/schemas/DateTimeInfo'
        finishedAt:
          $ref: '#/components/schemas/DateTimeInfo'
        errorMessage:
          type: string
          description: Error message if the latest job failed
        content:
          $ref: '#/components/schemas/InsightsContentDto'
    InsightsContentDto:
      type: object
      properties:
        language:
          type: string
          description: ISO 639-1 language code of the insights
          example: es
        executiveSummary:
          $ref: '#/components/schemas/InsightSectionDto'
        organicNetworks:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InsightSectionDto'
          description: Per organic-network sections, keyed by network token (e.g. instagram)
        adsPlatforms:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/InsightSectionDto'
          description: Per ads-platform sections, keyed by platform token (e.g. google, facebookAds)
        bestPosts:
          $ref: '#/components/schemas/InsightSectionDto'
      description: Structured insights content per section. Null if no insight has been generated.