Fundamental Research Labs Usage API

openapi: 3.2.0
info:
  title: Shortcut Usage API
  version: 1.0.0
  description: 'Shortcut API lets teams automate spreadsheet workflows and export organization usage data programmatically.


    ## Getting Started


    ### Create an API key


    1. Go to shortcut.ai

    2. Navigate to **Settings → API Keys**

    3. Create a new API key


    External callers use an API key in the `Authorization` header as a Bearer token:

    `Authorization: Bearer sc-xxx`


    Authenticated Shortcut applications can call spreadsheet automation routes with

    the user''s Shortcut session or access token for run, upload, status, download,

    skills, and cancel operations. Non-browser applications send the JWT as a

    bearer token; Shortcut web applications may use the same JWT through the

    `shortcut_access_token` cookie in a credentialed request from a trusted

    Shortcut origin. `/verify` and webhooks require API key authentication because

    they depend on API key and webhook-secret state.


    Registered integrations can also use authorization-code OAuth with S256 PKCE

    and client authentication. The user approves `api:access`; the integration

    sends its OAuth access token as a Bearer token on spreadsheet routes. This

    preserves the user''s ownership, subscription, and credit checks. OAuth does not

    support API-key verification, webhooks, or organization usage export.


    ### Spreadsheet automation workflow


    1. **Verify your API key**: `GET /api/spreadsheets/verify`

    2. **Submit a job**: `POST /api/spreadsheets` with a prompt

    3. **Check status**: `GET /api/spreadsheets/:runId` (poll until completed, failed, or error)

    4. **Download result**: `GET /api/spreadsheets/:runId/download`


    ### Usage export workflow


    1. Open **Usage Metrics** in Shortcut.

    2. Copy the prefilled command from **Programmatic export**.

    3. Use the Usage API reference to customize date range, format, or grouping.


    ### Spreadsheet automation limits


    - Maximum 2000 concurrent jobs per API key

    - Job timeout: 30 minutes (configurable up to 120 minutes)'
tags:
- name: Usage
  description: Export team usage metrics for reporting, finance, and internal analytics. Usage Metrics in Shortcut provides a prefilled request with your team_id; use this reference to customize date range, format, or grouping.
paths:
  /api/v1/team/usage-export:
    get:
      summary: Export team usage metrics
      tags:
      - Usage
      description: Export stored team usage metrics as JSON or CSV. Historical data remains available when verification is missing or stale. reportingCoverage lists each UTC day as verified, unverified, stale, or live; totals are verified, partial, or provisional. Partial totals include all stored values but may be incomplete or outdated; missing unverified days do not establish zero usage. Today is live and provisional. CSV includes equivalent verification columns. The "pure cost" field is usage credits multiplied by the current active contract's credit_overage_rate in USD; it is a usage valuation at that rate, not an invoice total or provider cost. All viewers with usage metrics access receive dollar values when a valid contract rate is available. When there is no active contract or its rate is missing or non-positive, exports return credit metrics and omit dollar values. Usage Metrics in Shortcut provides a prefilled request with your team_id; use these query parameters to customize the date range, output format, and optional platform grouping. API keys must belong to a user with usage metrics access for the requested team or organization.
      parameters:
      - schema:
          type: string
        in: query
        name: team_id
        required: false
        description: Team or organization ID to export. Required for API-key integrations. Usage Metrics shows a prefilled request for the current organization.
      - schema:
          type: string
          enum:
          - day
          - week
          - month
          - 60days
          - 90days
          - all
          default: month
        in: query
        name: period
        required: false
        description: Relative date range when explicit dates are omitted. all starts at the later of usage tracking or team creation, while preserving any older stored usage.
      - schema:
          type: string
        in: query
        name: start_date
        required: false
        description: YYYY-MM-DD. Must be provided together with end_date; takes precedence over period.
      - schema:
          type: string
        in: query
        name: end_date
        required: false
        description: YYYY-MM-DD. Must be provided together with start_date; takes precedence over period.
      - schema:
          type: string
          default: UTC
        in: query
        name: timezone
        required: false
        description: IANA timezone used to resolve relative periods and day boundaries.
      - schema:
          type: string
          enum:
          - json
          - csv
          default: json
        in: query
        name: format
        required: false
        description: Response format.
      - schema:
          type: string
          enum:
          - summary
          - daily
          default: summary
        in: query
        name: report
        required: false
        description: CSV only. summary exports per-member totals; daily exports member usage by day.
      - schema:
          type: string
          enum:
          - platform
        in: query
        name: group_by
        required: false
        description: JSON only. Add platform usage breakdowns to the response.
      security:
      - apiKey: []
      responses:
        '200':
          description: Default Response
      operationId: getApiV1TeamUsageExport
      x-operation-id-source: derived
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key in Bearer token format: `Authorization: Bearer sc-xxx`'
    shortcutOAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth access token
      description: Delegated OAuth access token with api:access scope. Existing user permissions and billing apply.
    shortcutSession:
      type: http
      scheme: bearer
      bearerFormat: Shortcut Session
      description: First-party Shortcut application session or access token sent as an explicit Bearer token.
    shortcutCookie:
      type: apiKey
      in: cookie
      name: shortcut_access_token
      description: Shortcut web session cookie for credentialed fetch requests. Missing or untrusted Origin headers are rejected.
x-provenance:
  method: harvested
  publisher: Fundamental Research Labs
  source: https://api.shortcut.ai/api/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)