Metricool Studio Api Service API

openapi: 3.2.0
info:
  title: Metricool Studio Api Service 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: Studio Api Service
paths:
  /v2/reporting/studio/reports:
    get:
      tags:
      - Studio Api Service
      summary: Get existing Studio reports by user identifier
      operationId: getReportList
      parameters:
      - name: forNotifications
        in: query
        description: Filter for notifications
        required: false
        schema:
          type: boolean
      - name: includeTotalVersions
        in: query
        description: Include total number of non-deleted versions per report
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseListStudioResponse'
    post:
      tags:
      - Studio Api Service
      summary: Create a new Studio report
      operationId: createReport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudioCreateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioResponse'
  /v2/reporting/studio/reports/shortcuts:
    post:
      tags:
      - Studio Api Service
      summary: Create a new Studio report from a contextual shortcut
      operationId: createShortcut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudioShortcutRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioResponse'
  /v2/reporting/studio/reports/{reportId}:
    delete:
      tags:
      - Studio Api Service
      summary: Delete existing Studio report by report ID
      operationId: deleteReport
      parameters:
      - name: reportId
        in: path
        description: Report ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBoolean'
  /v2/reporting/studio/reports/{reportId}/anonymous-link:
    get:
      tags:
      - Studio Api Service
      summary: Get the current anonymous access link for a Studio report
      operationId: getAnonymousReportLink
      parameters:
      - name: reportId
        in: path
        description: Report ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioLinkInfo'
    post:
      tags:
      - Studio Api Service
      summary: Generate a new anonymous access link for a Studio report
      operationId: createAnonymousReportLink
      parameters:
      - name: reportId
        in: path
        description: Report ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      - name: timezone
        in: query
        description: IANA timezone of the brand (optional). When present, it is embedded in the public link so the anonymous viewer renders posts in the brand's local time.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioLinkInfo'
    delete:
      tags:
      - Studio Api Service
      summary: Revoke the anonymous access link for a Studio report.
      operationId: revokeAnonymousReportLink
      parameters:
      - name: reportId
        in: path
        description: Report ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
  /v2/reporting/studio/reports/{reportId}/versions:
    get:
      tags:
      - Studio Api Service
      summary: Get existing Studio report versions by report ID
      operationId: getReportVersions
      parameters:
      - name: reportId
        in: path
        description: Report ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseListStudioResponse'
  /v2/reporting/studio/reports/{reportId}/versions/active:
    get:
      tags:
      - Studio Api Service
      summary: Get the active version of an existing Studio report by report ID
      operationId: getActiveReportVersion
      parameters:
      - name: reportId
        in: path
        description: Report ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioResponse'
  /v2/reporting/studio/versions/{versionId}:
    get:
      tags:
      - Studio Api Service
      summary: Get existing Studio report version by version ID
      operationId: getReport
      parameters:
      - name: versionId
        in: path
        description: Version ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioResponse'
    delete:
      tags:
      - Studio Api Service
      summary: Delete existing Studio report version by version ID
      operationId: deleteReportVersion
      parameters:
      - name: versionId
        in: path
        description: Version ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseBoolean'
  /v2/reporting/studio/versions/{versionId}/polling:
    get:
      tags:
      - Studio Api Service
      summary: Get report version generation status for polling
      operationId: getReportPolling
      parameters:
      - name: versionId
        in: path
        description: Version ID
        required: true
        schema:
          type: string
        example: 25674c14-a879-4e1f-8fd7-c09243a10726
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonOkResponseStudioResponse'
components:
  schemas:
    StudioResponse:
      type: object
      properties:
        id:
          type: string
          description: Report version identifier
          example: 25674c14-a879-4e1f-8fd7-c09243a10726
        content:
          type: string
          description: Report content with charts and analysis if status is COMPLETED
        status:
          type: string
          description: Report status
          example: COMPLETED
          enum:
          - PENDING
          - GENERATING
          - COMPLETED
          - FAILED
        errorMessage:
          type: string
          description: Error message if status is FAILED
        errorType:
          type: string
          description: Machine-readable failure classification, present only when status is FAILED. Lets the UI offer the right recovery action.
          example: TIMEOUT
          enum:
          - TIMEOUT
          - EXECUTION
          - PARTIAL_AGENTS
          - AUTH
          - CANCELLED
          - UNKNOWN
        prompt:
          type: string
          description: User prompt to generate the report
        versionCreatedAt:
          $ref: '#/components/schemas/DateTimeInfo'
        studioCreatedAt:
          $ref: '#/components/schemas/DateTimeInfo'
        studioId:
          type: string
          description: Report identifier that contains all the report versions
          example: 25674c14-a879-4e1f-8fd7-c09243a10726
        name:
          type: string
          description: Name of the report
          example: Line chart during may 2025
        type:
          type: string
          description: Type of the report between Calendar and Analytics
          example: Calendar
          enum:
          - Calendar
          - Analytics
        period:
          type: string
          description: Period of the report
          example: 01-Feb-2026 - 28-Feb-2026
        networks:
          type: array
          description: Networks involved in the report
          example:
          - facebook
          - instagram
          items:
            type: string
            description: Networks involved in the report
            example: '["facebook","instagram"]'
            enum:
            - LINKEDIN
            - FACEBOOK
            - FBGROUP
            - PINTEREST
            - FACEBOOK_ADS
            - ADWORDS
            - GMB
            - TWITTER
            - INSTAGRAM
            - INSTAGRAM_BUSINESS
            - YOUTUBE
            - TWITCH
            - BLOG
            - TIKTOK_ADS
            - TIKTOK
            - TIKTOK_BUSINESS
            - THREADS
            - BLUESKY
        brands:
          type: array
          description: Brands involved in the report
          items:
            $ref: '#/components/schemas/BrandDto'
        accessBlockedReason:
          type: string
          description: 'Reason why the report is blocked, null when accessible. BRAND_DELETED: brand no longer exists, NO_PERMISSION: user lost FULL_ACCESS_STUDIO, DIFFERENT_OWNER: brand belongs to a different owner than the current brand context'
          enum:
          - BRAND_DELETED
          - NO_PERMISSION
          - DIFFERENT_OWNER
        totalVersions:
          type: integer
          description: Total number of non-deleted versions for the report. Only present when the caller requested includeTotalVersions=true.
          format: int32
          example: 3
        customLogoUrl:
          type: string
          description: 'Public URL of the custom logo shown in the anonymous viewer header. Always populated: the user''s custom logo URL when set, or the default Metricool logo otherwise.'
          example: https://metricool-download.s3.eu-west-1.amazonaws.com/studio-logo/12345/202605/abc123def456.png
        sharedLink:
          type: string
          description: Public shared URL of the report when an anonymous access link is active. Omitted when no link was ever generated or it has been disabled.
          example: https://app.metricool.com/c/abc123
        selected:
          type: boolean
          description: True for the active (last-successful) version. Only present in the versions list.
          example: true
        hasManualEdits:
          type: boolean
          description: True when the AI-generated elements of this version have been manually edited by its owner. Lets the UI warn that manual edits will not be preserved if the view is regenerated/refreshed.
          example: true
        totalAgents:
          type: integer
          description: Total number of agents that took part in generating this version. Absent (not present) for versions created before partial-results support — absence means "no agent info", NOT zero.
          format: int32
          example: 5
        failedAgents:
          type: integer
          description: 'Number of agents that failed while generating this version. Present together with totalAgents for new versions (0 when all agents succeeded); absent for legacy versions. Lets the UI render the partial-success case (Caso 3): some charts generated, some agents failed.'
          format: int32
          example: 1
        failedAgentDetails:
          type: array
          description: Detail of the agents that failed. Only present in the version detail (single-version endpoints); listing endpoints carry just the counters. Absent when there is no agent detail (e.g. legacy versions).
          items:
            $ref: '#/components/schemas/FailedAgentDto'
        shownVersionState:
          type: string
          description: 'Whether the displayed report version is the latest or a fallback to an older working version, and why. Only present in the reports listing; absent in single-version endpoints. LATEST: the shown version is the report''s most recent one. FALLBACK_WHILE_RUNNING: the most recent version is still running/enqueued, so the last working version is shown while it regenerates. FALLBACK_AFTER_FAILURE: the most recent version failed, so the last working version is shown instead.'
          example: LATEST
          enum:
          - LATEST
          - FALLBACK_WHILE_RUNNING
          - FALLBACK_AFTER_FAILURE
        metrifactCreatedAt:
          $ref: '#/components/schemas/DateTimeInfo'
        metrifactId:
          type: string
      description: Studio response from the service
    JsonOkResponseListStudioResponse:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: array
          items:
            $ref: '#/components/schemas/StudioResponse'
    StudioCreateRequest:
      required:
      - prompt
      type: object
      properties:
        prompt:
          maxLength: 15000
          minLength: 0
          type: string
          description: User prompt for the report generation
          example: Quiero un gráfico de barras que compare mis estadísticas de tiktok de todas mis marcas
        mode:
          type: string
          description: Generation mode
          example: Guided
          enum:
          - Guided
          - Expert
        customLogoUrl:
          maxLength: 2048
          minLength: 0
          type: string
          description: Public URL of a custom logo to display in the anonymous viewer header. Must be an HTTPS URL hosted on a Metricool S3/CDN domain. If null, the default Metricool logo is used.
          example: https://metricool-download.s3.eu-west-1.amazonaws.com/studio-logo/12345/202605/abc123def456.png
      description: Studio create request containing user prompt
    JsonOkResponseStudioResponse:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/StudioResponse'
    StudioShortcutRequest:
      required:
      - brandIds
      - mainPeriod
      - network
      - prompt
      - templateType
      type: object
      properties:
        templateType:
          minLength: 1
          type: string
          description: Identifier of the shortcut template to apply
          example: compare-periods
        network:
          minLength: 1
          type: string
          description: Social network the shortcut targets
          example: instagram
        brandIds:
          minItems: 1
          type: array
          description: Brand (blog) identifiers the shortcut report covers
          example:
          - '12345'
          items:
            type: string
            description: Brand (blog) identifiers the shortcut report covers
            example: '["12345"]'
        mainPeriod:
          $ref: '#/components/schemas/StudioPeriodDto'
        comparisonPeriod:
          $ref: '#/components/schemas/StudioPeriodDto'
        tableName:
          type: string
          description: Source table the insight is built from. Required for the 'table-insights' template; unused for 'compare-periods'.
          example: posts
        question:
          type: string
          description: Predefined question the insight answers. Required for the 'table-insights' template; unused for 'compare-periods'.
          example: What are my best performing posts and why?
        sortDirection:
          type: string
          description: Ranking direction ('asc' or 'desc') for the table-insights topContent chart, overriding the template's default. Unused for 'compare-periods'.
          example: asc
        prompt:
          minLength: 1
          type: string
          description: User prompt saved for refresh
          example: Focus on engagement metrics and compare growth trends
      description: Studio shortcut request describing a contextual, template-based report (e.g. period comparison or table insights)
    StudioLinkInfo:
      required:
      - link
      type: object
      properties:
        link:
          type: string
          description: The anonymous access link URL for the Studio report
          example: https://app.metricool.com/reporting/studio/public?token=eyJ...
        createdAt:
          $ref: '#/components/schemas/DateTimeInfo'
      description: Anonymous access link for a Studio report, including its creation date
    JsonOkResponseBoolean:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          type: boolean
    JsonPaging:
      type: object
      properties:
        next:
          type: string
    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
    BrandDto:
      required:
      - blogId
      - name
      type: object
      properties:
        blogId:
          type: integer
          description: Unique identifier of the brand
          format: int32
          example: 123456
        name:
          type: string
          description: Name of the brand
          example: My Brand
        logo:
          type: string
          description: URL of the brand logo
          example: https://example.com/logo.png
      description: Brand information associated to a Studio report
    StudioPeriodDto:
      required:
      - from
      - to
      type: object
      properties:
        from:
          minLength: 1
          pattern: \d{4}-\d{2}-\d{2}
          type: string
          description: Start date of the period (inclusive), ISO-8601 full-date (RFC 3339 full-date, YYYY-MM-DD)
          example: '2025-07-01'
        to:
          minLength: 1
          pattern: \d{4}-\d{2}-\d{2}
          type: string
          description: End date of the period (inclusive), ISO-8601 full-date (RFC 3339 full-date, YYYY-MM-DD)
          example: '2025-07-31'
      description: Date range for a Studio shortcut period
    FailedAgentDto:
      required:
      - agentName
      - taskIndex
      type: object
      properties:
        taskIndex:
          type: integer
          description: Zero-based position of the failed agent within the version's task list. The first agent is 0.
          format: int32
          example: 2
        agentName:
          type: string
          description: Name of the agent that failed
          example: engagement-agent
        errorType:
          type: string
          description: Machine-readable failure classification of this agent. Resolved leniently upstream, so it is always one of the allowed values.
          example: TIMEOUT
          enum:
          - TIMEOUT
          - EXECUTION
          - PARTIAL_AGENTS
          - AUTH
          - CANCELLED
          - UNKNOWN
      description: Detail of a single agent that failed while generating a Studio report version.
    JsonOkResponseStudioLinkInfo:
      type: object
      properties:
        metadata:
          type: object
        page:
          $ref: '#/components/schemas/JsonPaging'
        data:
          $ref: '#/components/schemas/StudioLinkInfo'