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

# One schedule, with its 25 most recent runs



## OpenAPI

````yaml /api/openapi.reference.json get /api/v1/schedules/{id}
openapi: 3.1.0
info:
  title: Mediamonster API
  version: v1
  summary: Run Mediamonster's skills and recipes on your files, from code.
  description: >-
    Every skill on mediamonster.app, over HTTP: the same providers, credit
    prices and plan ceilings as the Workbench.


    Send a file as a public `url`, an earlier `job_id`, a Vault `asset_id`, or a
    multipart `file`. Calls wait up to 150 seconds for the result; `wait: false`
    answers 202 at once with a `poll_url`.


    Each skill has its own operation below, with its options as a JSON Schema
    and its price under `x-mediamonster`. Recipes — a named sequence of steps —
    run through POST /api/v1/runs.


    The same catalogue is served over MCP at /api/mcp.
  contact:
    name: Mediamonster
    url: https://docs.mediamonster.app/api/overview
servers:
  - url: https://mediamonster.app
security:
  - bearer: []
tags:
  - name: Discovery
    description: What's here, open to anyone.
  - name: Account
    description: The account and workspace behind the key.
  - name: Skills
    description: The catalogue, and the generic run.
  - name: Analysis skills
    description: Skills that hand back data about the file — tags, boxes, facts, shots.
  - name: Audio skills
    description: Skills that hand back a recording.
  - name: Document skills
    description: Skills that hand back a document.
  - name: Image skills
    description: Skills that hand back a picture.
  - name: Text skills
    description: >-
      Skills that hand back words — a transcript, subtitles, copy — and leave
      the file as it was.
  - name: Video skills
    description: Skills that hand back a video.
  - name: Recipes
    description: Named sequences of steps, run on one file.
  - name: Batches
    description: >-
      The same steps once per row of a sheet, or every combination of a few
      lists.
  - name: Convert
    description: Change a file's format or size. Free.
  - name: Jobs
    description: Poll a skill run or a conversion.
  - name: Vault
    description: Your stored files.
  - name: Galleries
    description: Client galleries.
  - name: Automations
    description: >-
      Recipes that run on the clock, once or on repeat, with nobody pressing
      Run.
  - name: Uploads
    description: Files of any size your plan takes, sent straight to storage.
  - name: Webhooks
    description: >-
      Endpoints every settled job and run is posted to, and the log of each
      attempt.
externalDocs:
  url: https://docs.mediamonster.app/api/overview
paths:
  /api/v1/schedules/{id}:
    get:
      tags:
        - Automations
      summary: One schedule, with its 25 most recent runs
      operationId: getSchedule
      parameters:
        - name: id
          in: path
          required: true
          description: The schedule's id.
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/XRequestId'
      responses:
        '200':
          description: The schedule.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Schedule'
                  - type: object
                    properties:
                      runs:
                        type: array
                        items: {}
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      description: >-
        Your own id for this request — 8 to 128 letters, digits, `.`, `_`, `:`
        or `-`. Used in place of one we mint, and echoed back.
      schema:
        type: string
        pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$
  schemas:
    Schedule:
      type: object
      description: >-
        Steps, or a saved recipe, run on their own: on the clock, once or on
        repeat, or when files are posted to its link.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        enabled:
          type: boolean
        recipe:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
            name:
              type:
                - string
                - 'null'
            missing:
              type: boolean
            version:
              type:
                - integer
                - 'null'
              description: >-
                The version it stays on. Null follows the recipe: each run takes
                its latest.
            latest:
              type:
                - integer
                - 'null'
              description: The recipe's latest version.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
        repeat:
          type: string
          enum:
            - once
            - hourly
            - daily
            - weekly
            - monthly
        starts_at:
          type: string
          format: date-time
        at_minute:
          type: integer
          description: Minutes past local midnight.
        every_hours:
          type: integer
        weekdays:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
        month_day:
          type: integer
        timezone:
          type: string
        ends_after:
          type:
            - integer
            - 'null'
        when:
          type: string
          description: How it reads, such as "Weekdays at 09:00".
        source:
          type: string
          enum:
            - none
            - asset
            - folder
            - trigger
        trigger:
          type: string
          enum:
            - clock
            - webhook
            - upload
            - email
            - podcast
            - feed
            - youtube
          description: >-
            What starts it: the clock; a POST to `trigger_url` (`webhook`), or
            files dropped on the page there (`upload`); mail to `trigger_email`;
            or something new in the podcast, feed or channel at
            `trigger_source`, checked every 10 minutes.
        trigger_email:
          type:
            - string
            - 'null'
          description: >-
            For `email`: its address. Each attachment of mail sent to it is a
            run. Only for callers who may change it.
        trigger_source:
          type:
            - string
            - 'null'
          description: 'For `podcast`, `feed` and `youtube`: the feed it reads.'
        trigger_url:
          type:
            - string
            - 'null'
          description: >-
            For `webhook`: the path to POST files to, on this host. Only for
            callers who may change it. Anyone holding it can run the automation.
        most_runs_a_day:
          type:
            - integer
            - 'null'
          description: The most runs its link starts in any 24 hours. null is no limit.
        most_credits_a_month:
          type:
            - integer
            - 'null'
          description: >-
            The most credits its runs spend in a calendar month, in its
            `timezone`. A run that would go past it is skipped until the month
            turns. null is no limit.
        credits_this_month:
          type:
            - integer
            - 'null'
          description: >-
            What its runs have spent this calendar month, counting a run still
            going at its quote. null when it has no `most_credits_a_month`.
        send_webhook_url:
          type:
            - string
            - 'null'
          description: >-
            Where each run's outcome is posted, signed like a run's own
            `webhook_url`.
        only_if:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/OnlyIfCondition'
          description: >-
            For `folder` and `trigger`: the conditions every incoming file has
            to meet to start a run. The rest are skipped, at no cost. null is
            every file.
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/RecipeInput'
          description: 'What its steps ask to be told: the `{{names}}` in them.'
        input_values:
          type: object
          additionalProperties:
            type: string
          description: >-
            The values those run with. A request to its link can send its own
            `inputs`, which win for that request.
        most_upload_mb:
          type:
            - integer
            - 'null'
          description: >-
            For `upload`: the largest file its page takes, in MB. null is the
            plan's.
        source_asset:
          type:
            - object
            - 'null'
          description: The first of `source_assets`.
        source_assets:
          type: array
          description: 'For `asset`: every Vault file each run starts from, one run each.'
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
        source_folder:
          type:
            - string
            - 'null'
        most_files:
          type: integer
        output_folder:
          type: string
        next_run_at:
          type:
            - string
            - 'null'
          format: date-time
        last_run_at:
          type:
            - string
            - 'null'
          format: date-time
        run_count:
          type: integer
        paused:
          type:
            - object
            - 'null'
        finished:
          type: boolean
        estimate:
          type: object
          properties:
            credits:
              type: integer
            label:
              type: string
        created_by:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        can_edit:
          type: boolean
    Step:
      type: object
      description: >-
        One step: a skill's slug (or `convert`, `resize`, `route`), its options,
        and a prompt for the steps that take one.
      properties:
        tool:
          type: string
          examples:
            - background-remover
        options:
          type: object
          additionalProperties:
            type: string
        prompt:
          type: string
        nested:
          type: boolean
          description: >-
            Runs only on what the step above made. Only means anything under a
            generator.
      required:
        - tool
    OnlyIfCondition:
      type: object
      description: >-
        One thing an incoming file has to be, such as `{"if": "kind", "in":
        ["video"]}` or `{"if": "longer", "seconds": 30}`. One of each `if` at
        most.
      properties:
        if:
          type: string
          enum:
            - kind
            - longer
            - shorter
            - shape
            - smaller
            - name
        in:
          type: array
          items:
            type: string
            enum:
              - image
              - video
              - audio
              - document
              - portrait
              - landscape
              - square
          description: >-
            For `kind`: image, video, audio or document. For `shape`: portrait,
            landscape or square.
        seconds:
          type: integer
          minimum: 1
          maximum: 86400
          description: For `longer` and `shorter`.
        mb:
          type: number
          exclusiveMinimum: 0
          description: For `smaller`, in MB.
        has:
          type: string
          maxLength: 80
          description: 'For `name`: text the file''s name contains, whatever the case.'
      required:
        - if
    RecipeInput:
      type: object
      description: >-
        One `{{name}}` a recipe's steps use, and how it is asked for. With no
        settings of its own an input is text, and required.
      properties:
        name:
          type: string
          description: 'The key `inputs` takes: `{{Product name}}` is `product_name`.'
        label:
          type: string
        kind:
          type: string
          enum:
            - text
            - long_text
            - number
            - link
            - choice
        required:
          type: boolean
        default:
          type:
            - string
            - 'null'
          description: What a run uses when none is sent.
        choices:
          type:
            - array
            - 'null'
          items:
            type: string
          description: 'For `choice`: the values it takes.'
      required:
        - name
        - label
        - kind
        - required
        - default
        - choices
    Error:
      type: object
      description: >-
        Every refusal. `code` is stable and meant for programs; `message` is a
        sentence meant for people, and says what to do.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
                - missing_file
                - bad_option
                - rate_limited
            message:
              type: string
            doc_url:
              type: string
              format: uri
              description: >-
                The heading on the errors page that explains this code and its
                fix.
              examples:
                - https://docs.mediamonster.app/api/errors#bad_option
            request_id:
              type: string
              description: The same id as the `X-Request-Id` header. Quote it to support.
              examples:
                - req_8fK2mQ0x7ZtLw3nVb1cR9dYe
            param:
              type: string
              description: The one field at fault, when there is one.
              examples:
                - edges
                - url
          required:
            - code
            - message
            - doc_url
            - request_id
      required:
        - error
  headers:
    X-Request-Id:
      description: >-
        This request's id — yours, if you sent a well-formed `X-Request-Id`. The
        same as `error.request_id`. Quote it to support.
      schema:
        type: string
        examples:
          - req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    X-RateLimit-Limit:
      description: Requests a minute this key may make. Absent on a plan with no limit.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: How many of them are left this minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When this minute's window ends, in unix seconds.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >-
        The request can't run as sent. Codes: missing_file, bad_option,
        unknown_option, bad_url, fetch_failed, bad_json, bad_file, wrong_input,
        missing_steps, bad_line, ambiguous_line, bad_recipe, bad_webhook,
        bad_upload_id, bad_idempotency_key, missing_input, bad_input,
        unknown_input, bad_inputs.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: missing_file
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#missing_file
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    Unauthorized:
      description: >-
        No key, or a key that isn't valid. Codes: missing_key, invalid_key,
        key_expired.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: missing_key
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#missing_key
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    Forbidden:
      description: >-
        The key's scopes, addresses, mode, plan or role don't allow it. Codes:
        insufficient_scope, ip_not_allowed, test_mode_unsupported,
        plan_required, plan_limit, not_allowed.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: insufficient_scope
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#insufficient_scope
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    NotFound:
      description: >-
        Nothing with that id or slug that this key can see. Codes:
        unknown_skill, job_not_found, run_not_found, recipe_not_found,
        recipe_version_not_found, file_not_found, rule_not_found.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unknown_skill
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#unknown_skill
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    RateLimited:
      description: >-
        Over the key's, or the account's, requests a minute. Codes:
        rate_limited, free_tool_limit.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        retry-after:
          description: Seconds to wait.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#rate_limited
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: mm_live_… or mm_test_…
      description: >-
        `Authorization: Bearer mm_live_…`. Mint a key at mediamonster.app/keys;
        every plan includes the API. A test key, `mm_test_…`, runs every check a
        live key does and spends nothing: each run finishes at once with a
        stand-in file, and says `livemode: false`. A key does only what its
        scopes allow.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.