> ## 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.

# Run the same steps once per row

> Each row is a run, charged and refunded step by step. A few run at a time; the batch pauses before it would spend past `budget`, or when the balance runs out. With `dry_run`, every row is checked and the batch priced, and nothing runs.



## OpenAPI

````yaml /api/openapi.reference.json post /api/v1/batches
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/batches:
    post:
      tags:
        - Batches
      summary: Run the same steps once per row
      description: >-
        Each row is a run, charged and refunded step by step. A few run at a
        time; the batch pauses before it would spend past `budget`, or when the
        balance runs out. With `dry_run`, every row is checked and the batch
        priced, and nothing runs.
      operationId: runBatch
      parameters:
        - name: dry_run
          in: query
          required: false
          description: >-
            `true` to check and price the run without running it. Same as
            `dry_run` in the body.
          schema:
            type: boolean
            default: false
        - $ref: '#/components/parameters/XRequestId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: 'With `dry_run`: what it would cost.'
          content:
            application/json:
              schema:
                type: object
          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'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '202':
          description: Started. Poll `poll_url`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
          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'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/TooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMedia'
        '422':
          $ref: '#/components/responses/Unprocessable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
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}$
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Retry this POST safely: the first request with a key runs and its answer
        is kept for a day; a retry with the same key and the same request gets
        that answer again, marked `Idempotent-Replayed: true`, instead of
        running twice. 1–255 printable characters — a UUID is a good one.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BatchRequest:
      type: object
      description: >-
        The steps, with `{{column}}` wherever a row's value goes, and the rows:
        one of `rows`, `csv` or `matrix`. A file every row starts from is `url`,
        `upload_id`, `job_id` or `asset_id`; a file per row is a column of links
        or Vault ids named by `file_column`.
      properties:
        url:
          type: string
          format: uri
        upload_id:
          type: string
          format: uuid
        job_id:
          type: string
          format: uuid
        asset_id:
          type: string
          format: uuid
        recipe:
          type: string
          description: As POST /api/v1/runs takes it.
        steps:
          type: array
          items:
            $ref: '#/components/schemas/Step'
          minItems: 1
        output:
          $ref: '#/components/schemas/Output'
        rows:
          type: array
          maxItems: 1000
          items:
            type: object
            additionalProperties:
              type: string
          description: >-
            One object per row. Its keys are the variables: `Product Name` is
            `{{product_name}}`.
        csv:
          type: string
          description: A sheet's text, header row first.
        matrix:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
            maxItems: 50
          description: >-
            Up to 4 lists. Every value is run with every value of every other
            list.
        file_column:
          type: string
          description: >-
            The column holding each row's file: a link (a direct file, a video
            site, a Drive or Dropbox share, a podcast episode) or a Vault file
            id. A link two rows share is fetched once. A picture option such as
            `end-frame` can hold `{{column}}` too, for a picture per row.
        naming:
          type: string
          description: >-
            What each result is called, from its row: `{{sku}}-{{colour}}`.
            `{{row}}` is the row's number.
        budget:
          type: integer
          minimum: 1
          description: >-
            The most credits the batch spends. It pauses before a row would take
            it over.
        check:
          type: object
          properties:
            retries:
              type: integer
              minimum: 0
              maximum: 3
              default: 1
            strict:
              type: boolean
              description: Make borderline pictures again too.
          description: >-
            Check each picture and make the ones that fail again, up to
            `retries` times.
        locks:
          type: object
          properties:
            style:
              type: string
              description: Words added to the end of every prompt.
            brand:
              type: string
              description: A brand id every step that takes a brand uses.
        name:
          type: string
        webhook_url:
          type: string
          format: uri
          description: Told once, when every row has settled.
        dry_run:
          type: boolean
          default: false
          description: >-
            Check everything and answer with the price instead of running. Also
            taken as `?dry_run=true`.
    Batch:
      type: object
      description: A batch and a page of its rows.
      properties:
        id:
          type: string
          format: uuid
        object:
          const: batch
        name:
          type: string
        status:
          type: string
          enum:
            - running
            - paused
            - complete
            - cancelled
        paused_reason:
          type:
            - string
            - 'null'
          description: '`budget`, `credits`, or null.'
        rows:
          type: object
          properties:
            total:
              type: integer
            waiting:
              type: integer
            running:
              type: integer
            complete:
              type: integer
            failed:
              type: integer
            skipped:
              type: integer
        credits_charged:
          type: integer
        budget:
          type:
            - integer
            - 'null'
        failed_inputs:
          type: array
          description: >-
            Every row whose own link couldn't be fetched — its file, or its
            picture in a `{{column}}` option — across all rows, not only this
            page. `row` is the row's `index`. Those rows failed without being
            charged; the others ran.
          items:
            type: object
            properties:
              row:
                type: integer
              url:
                type: string
              reason:
                type: string
            required:
              - row
              - url
              - reason
        items:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              row:
                type: object
                additionalProperties:
                  type: string
              status:
                type: string
                enum:
                  - waiting
                  - running
                  - complete
                  - failed
                  - skipped
              review:
                type:
                  - string
                  - 'null'
                enum:
                  - approved
                  - rejected
                  - null
              tries:
                type: integer
              run_id:
                type:
                  - string
                  - 'null'
              credits_charged:
                type: integer
              error:
                type:
                  - string
                  - 'null'
              outputs:
                type: array
                items:
                  type: object
        page:
          type: object
        poll_url:
          type: string
        results_url:
          type: string
    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
    Output:
      description: >-
        Save as, applied to the finished file: {"format": "webp", "quality":
        "85"}. Or a list of up to 5, one file each, all made from the last
        step's file: [{"format": "png"}, {"format": "webp"}]. In a list,
        `format` takes png, jpeg or webp. An entry that changes nothing on the
        finished file makes no file. The extra files are free.
      oneOf:
        - type: object
          additionalProperties:
            type: string
        - type: array
          minItems: 1
          maxItems: 5
          items:
            type: object
            additionalProperties:
              type: string
    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
    Idempotent-Replayed:
      description: >-
        `true` when this is the kept answer to an earlier request with the same
        `Idempotency-Key`, handed back instead of running again.
      schema:
        type: string
        enum:
          - 'true'
  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
    PaymentRequired:
      description: 'Not enough credits for this run. Codes: insufficient_credits.'
      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_credits
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#insufficient_credits
              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
    Conflict:
      description: >-
        The thing named isn't in a state to do this. Codes: job_busy,
        upload_unfinished, upload_completing, job_not_finished,
        idempotency_in_progress.
      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: job_busy
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#job_busy
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    TooLarge:
      description: >-
        The file is over the plan's ceiling, or the request body over 100 MB.
        Codes: file_too_large.
      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: file_too_large
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#file_too_large
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    UnsupportedMedia:
      description: 'The file isn''t one we take. Codes: unsupported_media.'
      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: unsupported_media
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#unsupported_media
              request_id: req_8fK2mQ0x7ZtLw3nVb1cR9dYe
    Unprocessable:
      description: >-
        Understood, but can't be done with this file. Codes: step_unavailable,
        nothing_to_save, idempotency_key_reused.
      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: step_unavailable
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#step_unavailable
              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
    Unavailable:
      description: >-
        Switched off here, or briefly unreachable. Codes: api_unavailable,
        rate_limit_unavailable, webhooks_off, idempotency_unavailable.
      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: api_unavailable
              message: What went wrong, and what to do instead.
              doc_url: https://docs.mediamonster.app/api/errors#api_unavailable
              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.