---
title: "Create Run"
method: POST
path: "/api/v1/runs/"
tags: ["runs"]
---

# Create Run

`POST /api/v1/runs/`

Submit a new run.

## Request body

- RunCreate — POST /runs request body.
  - `workflow` string, required — Git URL of the Snakemake workflow repository to clone and run.
  - `git_ref` string, nullable — Git branch, tag, or commit SHA to check out. Defaults to the repository's default branch.
  - `configfile` string, nullable — Path to a Snakemake config file in the workflow repo.
  - `snakemake_args` string[], nullable — Additional snakemake arguments appended to the backend's execution defaults. No need to pass own execution defaults like `--cores` or `--profile`.
  - `extra_files` object, nullable — Files written into the working directory before execution. Keys are repo-relative paths, values are file contents.
  - `env_vars` object, nullable — Environment variables set before execution. Keys are variable names, values are their contents.
  - `cache` RunCache — Cache configuration for a run.
    - `key` string, required — Cache identifier. Runs sharing a key reuse each other's cached directories.
    - `dirs` string[], required — Directories to cache (e.g. `./data`).
  - `import_networks` string[], nullable — Paths of `.nc` output files to import as networks after the run completes.
  - `backend_id` string, uuid, nullable — Snakedispatch backend that executes this run. Required when more than one backend is active.
  - `visibility` 'public' | 'private' — Resource visibility options for access control
  - `callback_url` string, uri, nullable — Webhook invoked when the run finishes. Host must match the allowed callback domains setting.

## Response `201`

Successful Response

- RunResponse — Full run detail returned by the API.
  - `id` string, uuid, required
  - `status` 'PENDING' | 'SETUP' | 'RUNNING' | 'UPLOADING' | 'COMPLETED' | 'FAILED' | 'ERROR' | 'CANCELLED', required — Run status, mirrors Snakedispatch's JobStatus.
  - `owner` UserPublicResponse, required — Minimal public user info for embedding in other responses
    - `id` string, uuid, required
    - `username` string, required
    - `avatar_url` string, nullable
  - `visibility` 'public' | 'private' — Resource visibility options for access control
  - `backend` BackendPublicResponse, required — Backend info visible to regular users (no internal URL).
    - `id` string, uuid, required
    - `name` string, required
    - `is_active` boolean, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `workflow` string, required
  - `configfile` string, nullable
  - `git_ref` string, nullable
  - `git_sha` string, nullable
  - `total_job_count` integer, nullable
  - `jobs_finished` integer, nullable
  - `snakemake_args` string[], nullable
  - `extra_files` object, nullable
  - `cache` RunCache — Cache configuration for a run.
    - `key` string, required — Cache identifier. Runs sharing a key reuse each other's cached directories.
    - `dirs` string[], required — Directories to cache (e.g. `./data`).
  - `import_networks` string[], nullable
  - `callback_url` string, nullable
  - `networks` RunNetworkSummary[]
    - `id` string, uuid, required
    - `name` string, nullable
    - `filename` string, required
    - `source_path` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/pypsa/apis/pypsa-app.md) · [All operations](https://skmtc.dev/pypsa/apis/pypsa-app/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pypsa/pypsa-app/revisions/a9fc864817c3/schema)