> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.instabase.com/api-sdk/api-reference/runs/run-deployment/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server.

# Run deployment

POST https://aihub.instabase.com/api/v2/apps/deployments/{deployment-id}/runs
Content-Type: application/json

Run an AI Hub deployment by its deployment ID. The input for the run is specified using a batch ID or file path.Use the UI to optionally [configure email notifications or webhooks](/automate/deployments#configuring-notifications) for certain events within the deployed app's lifecycle.Any specified input or output is validated against the context set by the `IB-Context` header.

Reference: https://docs.instabase.com/api-sdk/api-reference/runs/run-deployment

## Authentication

- `Authorization` header (bearer token, required) — Bearer HTTP authentication.

## Request

### Path parameters

- `deployment-id` (string, required) — The deployment ID.Find the deployment ID by opening the deployment in AI Hub and looking at the site URL, such as https://aihub.instabase.com/deployments/**01902d6f-bb35-74cb-bd27-c09b38bbf20a**/runs.

### Headers

- `IB-Context` (string, optional) — Typically your organization ID. See [Authorization and context identification](/api-sdk/authorization#ib-context-header) for details.

### Body (application/json)

This endpoint expects an object.

- `batch_id` (integer, optional) — 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, optional) — 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, optional) — 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` (double, optional) — 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` (double, optional) — 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, optional) — Version of the app to use. If not specified, defaults to the latest production version.
- `output_dir` (string, optional) — 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, optional) — JSON object containing settings for the deployment run.

## Response

### 202

Successfully initiated an asynchronous operation to run the deployment.

- `id` (string, optional) — Run ID of the run.
- `status` (enum, optional) — 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
  - Allowed values: `CANCELLED`, `COMPLETE`, `FAILED`, `PAUSED`, `RUNNING`, `STOPPED_AT_CHECKPOINT`
- `start_timestamp` (long, optional) — When the run started, in Unix time nanoseconds.
- `finish_timestamp` (long, optional, nullable) — When the run finished, in Unix time nanoseconds. `null` if run is still in progress.
- `msg` (string, optional, nullable) — Message about the run.
- `batch_id` (integer, optional, nullable) — The batch ID used as input for this run.
- `input_dir` (string, optional, nullable) — The path of the input folder used for this run.
- `app_id` (string, optional, nullable) — The app ID of the app that was run.
- `deployment_id` (string, optional, nullable) — The deployment ID used for this run.
- `tags` (list of string, optional, nullable) — List of string tags attached to this run.

## Types

### V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettings

JSON object containing settings for the deployment run.

- `keys` (V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsKeys, optional) — 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.
- `runtime_config` (V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfig, optional) — A dictionary supporting select runtime configurations, such as generating retrievable PDFs of processed documents. For all other runtime configurations, use the `keys` parameter.
- `tags` (list of string, optional) — List of string tags to attach to this run. Combined length of all tags must not exceed 500 characters.
- `step_timeout` (integer, optional) — Per-step timeout for this run, in seconds. Each step in the deployed app has its own default timeout, and this setting changes it for this run only. - `0`, or omitted: the run uses the step timeout set in the deployment's configuration. If the deployment has none, each step uses its default timeout. - A positive number of seconds: each step's timeout is raised to at least this value. A value lower than a step's default has no effect on that step. Steps with no default timeout stay unlimited. Any other value returns a 400 error. A run still stops after 11 hours in each processing stage, and individual operations such as OCR keep their own timeouts.

### 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` (map from string to any, optional) — 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.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.
- `secret` (map from string to string, optional) — 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/).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.

### 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, optional) — 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.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`.
- `instabase` (V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabase, optional) — A dictionary supporting select runtime configurations.

### V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabase

A dictionary supporting select runtime configurations.

- `pdf` (V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabasePdf, optional) — A dictionary supporting select runtime configurations dealing with PDF input documents.

### V2AppsDeploymentsDeploymentIdRunsPostRequestBodyContentApplicationJsonSchemaSettingsRuntimeConfigInstabasePdf

A dictionary supporting select runtime configurations dealing with PDF input documents.

- `passwords` (map from string to string, optional) — A dictionary with titles of encrypted PDF documents as keys and passwords for those documents as values.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "id": "string",
  "status": "CANCELLED",
  "start_timestamp": 1,
  "finish_timestamp": 1,
  "msg": "string",
  "batch_id": 1,
  "input_dir": "string",
  "app_id": "string",
  "deployment_id": "string",
  "tags": [
    "string"
  ]
}
```

**SDK Code**

```python Use batch ID with SDK
from aihub import AIHub

client = AIHub(
    api_root="https://aihub.instabase.com/api",
    api_key="abcdefghijklmnopqrst1234567890",
    ib_context="john.doe_acme.com"
)

run = client.apps.deployments.runs.create(
    deployment_id="12345678-abcde-1234-abcd-123456789012",
    batch_id=12345
)

print(f"run ID: {run.id}")

```

```python Use batch ID without SDK
import requests

deployment_id = "12345678-abcde-1234-abcd-123456789012"
url = f"https://aihub.instabase.com/api/v2/apps/deployments/{deployment_id}/runs"

headers = {
    "Authorization": "Bearer abcdefghijklmnopqrst1234567890",
    "IB-Context": "john.doe_acme.com"
}

# create the request payload
data = {"batch_id": 12345}

# make the POST request
response = requests.post(url, headers=headers, json=data)

# handle the response
if response.status_code == 202:
    print(f"Deployment run started with ID: {response.json()['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

```

```python Use input dir with SDK
from aihub import AIHub

client = AIHub(
    api_root="https://aihub.instabase.com/api",
    api_key="abcdefghijklmnopqrst1234567890",
    ib_context="john.doe_acme.com"
)

organization_id = "acme"
workspace = "MyWorkspace"
drive_name = "My Google Drive"
folder = "My Drive/input_files/documents/"
input_dir = f"{organization_id}/{workspace}/fs/{drive_name}/{folder}"

run = client.apps.deployments.runs.create(
    deployment_id="12345678-abcde-1234-abcd-123456789012",
    input_dir=input_dir
)

print(f"run ID: {run.id}")

```

```python Use input dir without SDK
import requests

deployment_id = "12345678-abcde-1234-abcd-123456789012"
url = f"https://aihub.instabase.com/api/v2/apps/deployments/{deployment_id}/runs"

headers = {
    "Authorization": "Bearer abcdefghijklmnopqrst1234567890",
    "IB-Context": "john.doe_acme.com"
}

organization_id = "acme"
workspace = "MyWorkspace"
drive_name = "My Google Drive"
folder = "My Drive/input_files/documents/"
input_dir = f"{organization_id}/{workspace}/fs/{drive_name}/{folder}"

# create the request payload
data = {"input_dir": input_dir}

# make the POST request
response = requests.post(url, headers=headers, json=data)

# handle the response
if response.status_code == 202:
    print(f"Deployment run started with ID: {response.json()['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

```

```javascript
const url = 'https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://aihub.instabase.com/api/v2/apps/deployments/deployment-id/runs")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```