---
title: "Run app"
method: POST
path: "/v2/apps/runs"
tags: ["runs"]
---

# Run app

`POST /v2/apps/runs`

Run an automation app by its name or app ID. The input for the run can be a batch ID or an input file path.

<Tip>

Running an automation app via a deployment is generally preferred over running an app directly.

Deployments offer additional features including upstream and downstream integrations, deployment metrics, human review workflows, and secret and configuration management.

Learn more about [deployments](/automate/deployments) to decide if you'd rather use the [Run deployment](/api-sdk/api-reference/runs/run-deployment) API operation.

</Tip>

<Note>Any specified input or output is validated against the context set by the `IB-Context` header.</Note>

## Headers

- `Authorization` string, required
- `IB-Context` string

## Request body

- object
  - `app_name` string — Required unless using `app_id`. The name of the app to run.
  - `app_id` string — Required unless using `app_name`. The app ID of the app to run. <Tip>You can find an app ID in the app URL, such as http<span>s://</span>aihub.instabase.com/hub/apps/**528c36e8-ac5b-490d-a41b-7eec9c404b87**.</Tip>
  - `owner` string — The account that generated the app. If not specified, defaults to your AI Hub username. For custom apps belonging to you, accept the default. For AI Hub Marketplace apps published by Instabase, specify `instabase`.
  - `batch_id` integer — Required unless using `input_dir`. The batch ID of a batch created with the [Batches endpoint](/api-sdk/api-reference/batches/create-batch/). All files uploaded to the batch are used as input for the run.
  - `input_dir` string — Required unless using `batch_id`. The path of the input folder in a connected drive or Instabase Drive. See [Specifying file paths](/api-sdk/api-reference/run-reference/).
  - `version` string — Version of the app to use. If not specified, defaults to the latest production version.
  - `output_workspace` string — The workspace in which to run the app. Output saves to the specified workspace. If not defined, the default is your personal workspace. <Note>Service accounts don't have personal workspaces. If making this call from a service account, you must specify a value for either `output_workspace` or `output_dir`.</Note>
  - `output_dir` string — Defines a specific location for the output to be saved in a connected drive or Instabase Drive. If defined, overrides the `output_workspace` value. See [Specifying file paths](/api-sdk/api-reference/run-reference/).
  - `settings` V2AppsRunsPostRequestBodyContentApplicationJsonSchemaSettings — JSON object containing settings for the app run.
    - `keys` V2AppsRunsPostRequestBodyContentApplicationJsonSchemaSettingsKeys — Configure runtime values for any custom and secret keys referenced in the app. Undefined keys run without a value.
      - `custom` object — Configure any custom keys, using key/value pairs. In the key/value pair, define the key as the name of an existing key used in your app, and define the value as any custom value. <Note>Any keys being defined by API should correspond to keys listed on the app **Overview** page, on the **Keys** tab.</Note>
      - `secret` object — Configure any secret keys, using key/value pairs. In the key/value pair, define the key as the name of an existing secret key used in your app, and define the value as any secret in the organization's secrets vault. For guidance on managing secrets, see [Managing secrets](/admin/secret-management/) or refer to the [Secrets endpoints](/api-sdk/api-reference/secrets/). <Note>Any keys being defined by API should correspond to keys listed on the app **Overview** page, on the **Keys** tab.</Note>
    - `runtime_config` V2AppsRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfig — A dictionary supporting select runtime configurations, such as generating retrievable PDFs of processed documents. For all other runtime configurations, use the `keys` parameter.
      - `generate_post_process_pdf` boolean — Set to `true` to generate a retrievable PDF for each document the app processes, including separate PDFs for each document created by split classification. PDF generation is supported only for documents less than 100 pages in length. <Note>When getting run results, use the [`include_source_info` query parameter](/api-sdk/api-reference/runs/get-run-results#request.query.include_source_info.include_source_info) to return the file path for any generated PDFs in your results. File paths are returned under `files/documents/post_processed_pdf_path`.</Note>
      - `instabase` V2AppsRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabase — A dictionary supporting select runtime configurations.
        - `pdf` V2AppsRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabasePdf — A dictionary supporting select runtime configurations dealing with PDF input documents.
          - `passwords` object — A dictionary with titles of encrypted PDF documents as keys and passwords for those documents as values.
    - `tags` string[] — List of string tags to attach to this run. Combined length of all tags must not exceed 500 characters.

## Response `200`

Run started successfully.

- Run
  - `id` string — Run ID of the run.
  - `status` 'CANCELLED' | 'COMPLETE' | 'FAILED' | 'PAUSED' | 'RUNNING' | 'STOPPED_AT_CHECKPOINT' — Status of the run. Possible values and meanings: - `CANCELLED` -- A user cancelled the run - `COMPLETE` -- The run successfully completed. A human review completed if it was required. Results are retrievable, but some fields may have failed and have the value `ERROR`. - `FAILED` -- The run failed to complete - `PAUSED` -- This status is reserved for future use - `RUNNING` -- The run is in progress and is not paused - `STOPPED_AT_CHECKPOINT` -- A validation error has paused the run for human review
  - `start_timestamp` integer — When the run started, in Unix time nanoseconds.
  - `finish_timestamp` integer, nullable — When the run finished, in Unix time nanoseconds. `null` if run is still in progress.
  - `msg` string, nullable — Message about the run.
  - `batch_id` integer, nullable — The batch ID used as input for this run.
  - `input_dir` string, nullable — The path of the input folder used for this run.
  - `app_id` string, nullable — The app ID of the app that was run.
  - `deployment_id` string, nullable — The deployment ID used for this run.
  - `tags` string[], nullable — List of string tags attached to this run.

---

[API](https://skmtc.net/instabase/apis/api-reference.md) · [All operations](https://skmtc.net/instabase/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/instabase/api-reference/revisions/3a4f46d48141/schema)