> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and limits

> What the workspace has used of its limits, and whether the next
AI job would be accepted.

Two 402s guard every AI verb — `usage_limit_exceeded` (the
weekly AI budget, the primary limit) and `spend_cap_exceeded`
(the daily API spend cap) — and this endpoint is the pre-flight
for both. Read `canGenerate` first: `false` means the next
post generation, image generation or knowledge ingest **will**
be refused, and `blockedBy` names which limit. `canGenerate` is
measured against the cost of a post generation, the most
common AI job.

AI budgets are reported as a **percentage** of the allowance,
never as money: the budget is denominated in provider cost, so
the meaningful figure for a customer is how much of the
allowance is gone. Storage is reported in bytes, and the daily
API cap in cents — both are already public (the cap appears in
the `spend_cap_exceeded` body).

With `projectId` the answer covers that project's weekly
budget; without one it covers the workspace pool and
`ai.project` is `null`. A company page has no budget of its own
and spends from the pool, which `ai.scope` names.

Required scope: `workspace:read`.




## OpenAPI

````yaml /openapi/v1.yaml get /usage
openapi: 3.1.0
info:
  title: Scripe Public API
  version: '2026-08-10'
  summary: >-
    Read and write Scripe workspace data — posts, notes, ideas, sources,
    knowledge, media, analytics, usage, async jobs, and webhooks.
  description: |
    The Scripe public API gives integrators stable, versioned access to a
    workspace's content surface: reads across every resource, synchronous
    writes (notes, posts, ideas, text sources, media assets), async jobs
    (post generation, file/URL/YouTube ingest, image and carousel
    generation), usage meters, and outbound webhooks.

    All endpoints (except `/v1/health`) require a Bearer token — either a
    workspace API key (`scripe_sk_*`) or an OAuth 2.1 access token
    (`scripe_oat_*`). Pin the API version with the `Scripe-Api-Version`
    request header to opt out of breaking changes.
  contact:
    name: Scripe Support
    url: https://scripe.io/support
    email: support@scripe.io
  license:
    name: Proprietary
servers:
  - url: https://api.scripe.io/v1
    description: Production
security:
  - BearerApiKey: []
tags:
  - name: Health
    description: Liveness and authenticated key smoke tests.
  - name: Workspace
    description: The workspace + principal resolved from your API key.
  - name: Projects
    description: Personal-brand, company-page, and amplifier projects.
  - name: Notes
    description: Project notes with paired calendar slot.
  - name: Posts
    description: Drafts, scheduled, and published LinkedIn posts.
  - name: Analytics
    description: Your own LinkedIn analytics and viral-post inspiration search.
  - name: Sources
    description: Transcriptions (audio/video sources) with truncated body.
  - name: Uploads
    description: >-
      Pre-signed S3 PUT URLs the customer uploads bytes to before referencing
      via Sources or Knowledge.
  - name: Knowledge
    description: >-
      Knowledge-base documents indexed for RAG. Async ingest via text, file,
      URL, or YouTube.
  - name: Jobs
    description: >-
      Async-job lifecycle — submitted via post-generation, knowledge ingest,
      file source.
  - name: Calendar
    description: >-
      The content calendar — scheduled/planned posts, note slots, idea
      placements, and the posting-time template.
  - name: Ideas
    description: >-
      The idea board — creative briefs with derived workflow statuses and
      date-level calendar placement.
  - name: Media
    description: >-
      Media-library search, own-image imports, AI image generation, and
      full-state media writes onto posts.
  - name: Settings
    description: >-
      Curated project settings, engagement policy, and company pages (read-only
      over REST).
  - name: Webhooks
    description: |
      Outbound HTTP callbacks. Subscribe an endpoint to one or more
      event names; we POST a signed JSON payload every time a matching
      event fires in the workspace. The signing secret is shown once
      on create and once on rotate — verify the
      `Webhook-Signature: t=<ts>,v1=<hmac>` header on every delivery.
paths:
  /usage:
    get:
      tags:
        - Workspace
      summary: Usage and limits
      description: |
        What the workspace has used of its limits, and whether the next
        AI job would be accepted.

        Two 402s guard every AI verb — `usage_limit_exceeded` (the
        weekly AI budget, the primary limit) and `spend_cap_exceeded`
        (the daily API spend cap) — and this endpoint is the pre-flight
        for both. Read `canGenerate` first: `false` means the next
        post generation, image generation or knowledge ingest **will**
        be refused, and `blockedBy` names which limit. `canGenerate` is
        measured against the cost of a post generation, the most
        common AI job.

        AI budgets are reported as a **percentage** of the allowance,
        never as money: the budget is denominated in provider cost, so
        the meaningful figure for a customer is how much of the
        allowance is gone. Storage is reported in bytes, and the daily
        API cap in cents — both are already public (the cap appears in
        the `spend_cap_exceeded` body).

        With `projectId` the answer covers that project's weekly
        budget; without one it covers the workspace pool and
        `ai.project` is `null`. A company page has no budget of its own
        and spends from the pool, which `ai.scope` names.

        Required scope: `workspace:read`.
      operationId: getUsage
      parameters:
        - $ref: '#/components/parameters/ScripeApiVersion'
        - name: projectId
          in: query
          required: false
          description: |
            Report the weekly AI budget of this project. Omit for the
            workspace pool alone.
          schema:
            type: string
            example: proj_project_40b15fd2eb034fa0
      responses:
        '200':
          description: Current usage and limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    ScripeApiVersion:
      name: Scripe-Api-Version
      in: header
      required: false
      description: |
        Pin the API version. Format `YYYY-MM-DD`. Omit to receive the
        currently rolling default. Unknown versions return `400
        version_unsupported`.
      schema:
        type: string
        example: '2026-08-10'
  schemas:
    UsageResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Usage'
    Usage:
      type: object
      required:
        - plan
        - canGenerate
        - blockedBy
        - ai
        - storage
        - apiSpend
      properties:
        plan:
          type: string
          example: BUSINESS
        canGenerate:
          type: boolean
          description: |
            Would the next AI job be accepted right now? Measured
            against the cost of a post generation. Considers usage
            limits only — not plan features and not scopes.
        blockedBy:
          description: Which limit says no. Null when `canGenerate` is true.
          oneOf:
            - type: string
              enum:
                - weekly_ai_budget
                - daily_api_spend_cap
            - type: 'null'
        ai:
          $ref: '#/components/schemas/UsageAi'
        storage:
          $ref: '#/components/schemas/UsageStorage'
        apiSpend:
          $ref: '#/components/schemas/UsageApiSpend'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
            - docs_url
          properties:
            code:
              type: string
              description: Stable, machine-readable error identifier.
              example: not_found
            message:
              type: string
            request_id:
              type: string
              example: req_a1b2c3d4e5f6
            docs_url:
              type: string
              format: uri
            details:
              description: Optional structured payload — shape varies per code.
    UsageAi:
      type: object
      required:
        - scope
        - percentUsed
        - unlimited
        - enforcement
        - weekStart
        - resetsAt
        - project
        - workspacePool
      properties:
        scope:
          type: string
          enum:
            - ai_project
            - ai_workspace_pool
          description: |
            Which budget governs the next AI job — the project's own,
            or the workspace pool (no project named, or a company page,
            which has no budget of its own).
        percentUsed:
          type: integer
          description: 0-100 of the governing budget. Always 0 when unlimited.
        unlimited:
          type: boolean
        enforcement:
          type: string
          enum:
            - 'off'
            - shadow
            - warn
            - block
          description: Only `block` refuses a job.
        weekStart:
          type: string
          example: '2026-08-10'
        resetsAt:
          type: string
          format: date-time
        project:
          oneOf:
            - $ref: '#/components/schemas/UsageAiProject'
            - type: 'null'
        workspacePool:
          $ref: '#/components/schemas/UsageMeter'
    UsageStorage:
      type: object
      required:
        - usedBytes
        - limitBytes
        - percentUsed
        - usedAssets
        - assetLimit
      properties:
        usedBytes:
          type: integer
        limitBytes:
          description: Null = unlimited.
          type:
            - integer
            - 'null'
        percentUsed:
          type: integer
        usedAssets:
          type: integer
        assetLimit:
          description: Null = unlimited.
          type:
            - integer
            - 'null'
    UsageApiSpend:
      type: object
      required:
        - bucketDate
        - capCents
        - spentCents
        - remainingCents
      properties:
        bucketDate:
          type: string
          description: UTC day of the bucket; resets at 00:00 UTC.
          example: '2026-08-14'
        capCents:
          description: Null = unlimited.
          type:
            - integer
            - 'null'
        spentCents:
          type: integer
        remainingCents:
          description: Null = unlimited.
          type:
            - integer
            - 'null'
    UsageAiProject:
      type: object
      required:
        - id
        - name
        - percentUsed
        - unlimited
      properties:
        id:
          type: string
        name:
          type: string
        percentUsed:
          type: integer
        unlimited:
          type: boolean
    UsageMeter:
      type: object
      required:
        - percentUsed
        - unlimited
      properties:
        percentUsed:
          type: integer
        unlimited:
          type: boolean
  responses:
    Unauthorized:
      description: Missing, malformed, expired, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Plan not eligible, scope missing, or workspace mismatch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found in this workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Sliding-window rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: scripe_sk_live_*
      description: |
        Pass `Authorization: Bearer scripe_sk_live_<...>` (or
        `scripe_sk_test_<...>` for test keys) on every request. Keys
        are scoped to a single workspace and can be revoked from the
        Scripe dashboard.

        The same header also accepts an OAuth 2.1 access token
        (`scripe_oat_*`); both credentials share one scope vocabulary
        and every operation below documents the scope it requires.
        An API key can hold every scope named on this surface except
        `webhooks:manage`, which is grantable to OAuth tokens only
        today — the webhook-endpoint operations answer
        `403 scope_missing` to every API key. Operations that name no
        scope accept any valid token of the workspace.

````