---
title: "Run a saved recipe or workflow"
method: POST
path: "/api/v1/recipes/{id}/run"
tags: ["Recipes"]
---

# Run a saved recipe or workflow

`POST /api/v1/recipes/{id}/run`

## Request

- Base URL: `https://api.popnow.ai`
- URL: `https://api.popnow.ai/api/v1/recipes/{id}/run`
- Auth: HTTP bearer

Compiles the recipe on the server with your inputs and starts a run (one task per piece; a workflow runs its steps in order,
each step using the earlier steps' results). Inputs you leave out use the material saved with the recipe.
Media inputs take `popnow://g/<job>/<n>` (a result), `popnow://f/<file>` (an upload), `popnow://a/<asset>` (an API asset) or an
https URL, or a list of them; the `prompt` input of a recipe (and text inputs of a workflow) take plain text.
The run is priced at current list prices first. With `maxCredits`, a run that would cost more is not started (409);
without it, the run starts at the quoted price. The run never spends more than that amount.
Keys with a model list or a spending limit can't run recipes (403). Replaying the same `Idempotency-Key` returns the same run.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `inputs` object: Input id → a reference, a list of references, or text.
  - `count` integer: How many pieces a recipe makes (workflows always run once).
  - `maxCredits` integer: The most this run may cost.

## Response `200`

The run started.

- object
  - `code` 200, required
  - `msg` string, required
  - `data` object, required
    - `runId` string, required
    - `estimatedCredits` integer, required
    - `steps` integer, required

## Other responses

- `400`: Invalid JSON, query, callback URL, model input, or media declaration. Invalid callBackUrl values return code 400 and msg "Invalid callback URL" with request_id. Submitted hosts, IP addresses, and DNS diagnostics are not echoed.
- `401`: Missing, malformed, expired, revoked, or otherwise invalid API key.
- `402`: Insufficient balance (`40201`) or a spend cap was reached (`40202`).
- `403`: Account, model, API-key, IP, or region authorization failed.
- `404`: Resource does not exist or is not visible to this account and API key. These cases are intentionally indistinguishable.
- `409`: Idempotency or media-transfer state conflicts with this request.
- `429`: Account-level request limit exceeded.
- `500`: Internal failure. Details are not exposed; report `request_id` to support.

## Changes

- **2026-10-20** `fede911a6e9b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/popnow/apis/popnow-api/changes/api/v1/recipes/:id/run/post.md)

---

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