---
title: "Create a new Studio report from a contextual shortcut"
method: POST
path: "/v2/reporting/studio/reports/shortcuts"
tags: ["Studio Api Service"]
---

# Create a new Studio report from a contextual shortcut

`POST /v2/reporting/studio/reports/shortcuts`

## Request

- Base URL: `https://app.metricool.com/api`
- URL: `https://app.metricool.com/api/v2/reporting/studio/reports/shortcuts`
- Auth: none declared

## Request body

- StudioShortcutRequest: Studio shortcut request describing a contextual, template-based report (e.g. period comparison or table insights)
  - `templateType` string, required: Identifier of the shortcut template to apply
  - `network` string, required: Social network the shortcut targets
  - `brandIds` string[], required: Brand (blog) identifiers the shortcut report covers
  - `mainPeriod` StudioPeriodDto, required: Date range for a Studio shortcut period
    - `from` string, required: Start date of the period (inclusive), ISO-8601 full-date (RFC 3339 full-date, YYYY-MM-DD)
    - `to` string, required: End date of the period (inclusive), ISO-8601 full-date (RFC 3339 full-date, YYYY-MM-DD)
  - `comparisonPeriod` StudioPeriodDto: Date range for a Studio shortcut period
    - `from` string, required: Start date of the period (inclusive), ISO-8601 full-date (RFC 3339 full-date, YYYY-MM-DD)
    - `to` string, required: End date of the period (inclusive), ISO-8601 full-date (RFC 3339 full-date, YYYY-MM-DD)
  - `tableName` string: Source table the insight is built from. Required for the 'table-insights' template; unused for 'compare-periods'.
  - `question` string: Predefined question the insight answers. Required for the 'table-insights' template; unused for 'compare-periods'.
  - `sortDirection` string: Ranking direction ('asc' or 'desc') for the table-insights topContent chart, overriding the template's default. Unused for 'compare-periods'.
  - `prompt` string, required: User prompt saved for refresh

## Response `200`

OK

- JsonOkResponseStudioResponse
  - `metadata` object
  - `page` JsonPaging
    - `next` string
  - `data` StudioResponse: Studio response from the service
    - `id` string: Report version identifier
    - `content` string: Report content with charts and analysis if status is COMPLETED
    - `status` 'PENDING' | 'GENERATING' | 'COMPLETED' | 'FAILED': Report status
    - `errorMessage` string: Error message if status is FAILED
    - `errorType` 'TIMEOUT' | 'EXECUTION' | 'PARTIAL_AGENTS' | 'AUTH' | 'CANCELLED' | 'UNKNOWN': Machine-readable failure classification, present only when status is FAILED. Lets the UI offer the right recovery action.
    - `prompt` string: User prompt to generate the report
    - `versionCreatedAt` DateTimeInfo
      - `dateTime` string, required: Local Date-time represented with a certain timezone
      - `timezone` string: Timezone applied to the datetime
    - `studioCreatedAt` DateTimeInfo
      - `dateTime` string, required: Local Date-time represented with a certain timezone
      - `timezone` string: Timezone applied to the datetime
    - `studioId` string: Report identifier that contains all the report versions
    - `name` string: Name of the report
    - `type` 'Calendar' | 'Analytics': Type of the report between Calendar and Analytics
    - `period` string: Period of the report
    - `networks` string[]: Networks involved in the report
    - `brands` BrandDto[]: Brands involved in the report
      - `blogId` integer, required: Unique identifier of the brand
      - `name` string, required: Name of the brand
      - `logo` string: URL of the brand logo
    - `accessBlockedReason` 'BRAND_DELETED' | 'NO_PERMISSION' | 'DIFFERENT_OWNER': 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
    - `totalVersions` integer: Total number of non-deleted versions for the report. Only present when the caller requested includeTotalVersions=true.
    - `customLogoUrl` string: 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.
    - `sharedLink` string: 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.
    - `selected` boolean: True for the active (last-successful) version. Only present in the versions list.
    - `hasManualEdits` boolean: 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.
    - `totalAgents` integer: 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.
    - `failedAgents` integer: 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.
    - `failedAgentDetails` FailedAgentDto[]: 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).
      - `taskIndex` integer, required: Zero-based position of the failed agent within the version's task list. The first agent is 0.
      - `agentName` string, required: Name of the agent that failed
      - `errorType` 'TIMEOUT' | 'EXECUTION' | 'PARTIAL_AGENTS' | 'AUTH' | 'CANCELLED' | 'UNKNOWN': Machine-readable failure classification of this agent. Resolved leniently upstream, so it is always one of the allowed values.
    - `shownVersionState` 'LATEST' | 'FALLBACK_WHILE_RUNNING' | 'FALLBACK_AFTER_FAILURE': 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.
    - `metrifactCreatedAt` DateTimeInfo
      - `dateTime` string, required: Local Date-time represented with a certain timezone
      - `timezone` string: Timezone applied to the datetime
    - `metrifactId` string

---

[API](https://skmtc.dev/metricool/apis/metricool-api.md) · [All operations](https://skmtc.dev/metricool/apis/metricool-api/llms.txt) · [OpenAPI document](https://skmtc.dev/metricool/apis/metricool-api/revisions/aea9d9a8415a?raw)