---
title: "Run deployment"
method: POST
path: "/v2/apps/deployments/{deployment-id}/runs"
tags: ["runs"]
---

# Run deployment

`POST /v2/apps/deployments/{deployment-id}/runs`

Run an AI Hub deployment by its deployment ID. The input for the run is specified using a batch ID or file path.

<Info>Use the UI to optionally [configure email notifications or webhooks](/automate/deployments#configuring-notifications) for certain events within the deployed app's lifecycle.</Info>

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

## Path parameters

- `deployment-id` string, required

## Headers

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

## Request body

- object
  - `batch_id` integer — Required unless using `input_dir` or `manual_upstream_integration`. 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` or `manual_upstream_integration`. The path of the input folder in a connected drive or Instabase Drive. See [Specifying file paths](/api-sdk/api-reference/run-reference/).
  - `manual_upstream_integration` boolean — Use the deployment's upstream integration as a source rather than a `batch_id` or `input_dir`. Requires an upstream integration to be configured for the deployment.
  - `from_timestamp` number, double — Required if `manual_upstream_integration` is true and the upstream integration is a mailbox integration. Specifies the earliest date in Unix time milliseconds from which to pull emails.
  - `to_timestamp` number, double — Required if `manual_upstream_integration` is true and the upstream integration is a mailbox integration. Specifies the latest date in Unix time milliseconds from which to pull emails.
  - `version` string — Version of the app to use. If not specified, defaults to the latest production version.
  - `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 configured for the deployment. See [Specifying file paths](/api-sdk/api-reference/run-reference).
  - `settings` V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettings — JSON object containing settings for the deployment run.
    - `keys` V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsKeys — Define the values for any custom or secret keys configured under your deployment's *Runtime configurations* settings. Key values passed via API override any key values defined in the deployment configuration.
      - `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 deployment, and define the value as any custom value. <Note>Any keys being defined by API should correspond to keys listed under your deployment's *Runtime configuration* settings. For keys included in the `custom` object, match against the keys listed on the **Custom keys** tab of the runtime configuration.</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 deployment, 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 under your deployment's *Runtime configuration* settings. For keys included in the `secret` object, match against the keys listed on the **Secret keys** tab of the runtime configuration.</Note>
    - `runtime_config` V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfig — 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` V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabase — A dictionary supporting select runtime configurations.
        - `pdf` V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabasePdf — 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 `202`

Successfully initiated an asynchronous operation to run the deployment.

- 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)