> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.instabase.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server. # Run automation apps by SDK > Process files by running automation apps using the AI Hub SDK. With the AI Hub software development kit (SDK), you can write a Python script to upload files and process them with an automation app. > **Tip** > > This guide covers the simplest way to run an automation app. Running a deployment is usually preferred over running apps directly. > > Deployments offer additional features including upstream and downstream integrations, deployment metrics, human review workflows, and secret and configuration management. > > To learn about deployments, see [Creating deployments](/automate/deployments#creating-deployments). To learn about running deployments programmatically, see the [run deployment](/api-sdk/api-reference/runs/run-deployment) endpoint. You can also use the API runner tool to generate code samples for running deployments by API. > > #### About the API runner tool... > > The AI Hub interface includes an API runner that generates code samples for running deployments by API. The API runner supports a variety of languages, though the generated code samples include basic, required parameters only. Additional parameters are listed in the [run deployment](/api-sdk/api-reference/runs/run-deployment) API reference. > > 1. From Workspaces, select the **Deploy** tab and open the deployment you want to run. > > 2. Click **Run with API**. The API runner pane opens. > > 3. Select a language and variant. > > 4. Follow the guidance in the interface, selecting your API token, workspace, and other details. This guide includes a [complete script](#complete-script) to use as a model for creating your own workflow. > **Info** > > The script in this guide uses the AI Hub SDK, but you can use the AI Hub API instead. For guidance, see the [batches](/api-sdk/api-reference/batches) and [runs](/api-sdk/api-reference/runs) endpoints. > **Before you begin** > > [Learn](/api-sdk/using-api-sdk) about the API and SDK and [install](/api-sdk/using-api-sdk#install-the-sdk) the SDK. ## Import modules and initialize the client Import key Python modules. ```python import os import time from aihub import AIHub ``` Initialize a client that lets you interact with the API through Python objects and methods. ```python # initialize the SDK client client = AIHub(api_root=, api_key=, ib_context=) ``` ### Parameter reference | Parameter | Type | Required | Description | | ------------ | ---- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_root` | str | No | The root URL of your AI Hub API. For **organization accounts** • If your organization has a custom AI Hub domain, use your organization's root API URL, such as `https://my-org.instabase.com/api`. • If your organization doesn't have a custom AI Hub domain, omit setting `api_root`. | | `api_key` | str | Yes | Your API token. | | `ib_context` | str | No, but recommended | The value for the `IB-Context` header that the SDK includes with all API requests. Set to your organization ID. | ## Upload files to a batch You can create a batch of files to use as input for your app run. You can add and remove files from the batch, but the batch ID remains constant so you can repeatedly use all files in the batch as app input. For more information, see the [batches](/api-sdk/api-reference/batches/) endpoint. Below the code you wrote to initialize the client, create a batch with `client.batches.create()` and upload files to it with `client.batches.add_file()`. ```python # create a batch batch = client.batches.create(name=) # add files to the batch file_paths = [, ] for path in file_paths: with open(path, 'rb') as file: client.batches.add_file(batch_id=batch.id, file_name=os.path.basename(path), file=file) ``` ### Parameter reference | Parameter | Type | Required | Description | | ------------ | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | str | Yes | User-defined name of the batch. Maximum length is 255 characters. | | `file_paths` | list\[str] | Yes | Paths to one or more local files to upload to the batch. Each path is a separate string. All paths are collected in a list, even if there's only one path. | ## Process files through an automation app After uploading your files to a batch, you can process them using an automation app. With the SDK, you can run the app, check the status of your app run, and when the run is complete, get the results. For more information, see the [runs](/api-sdk/api-reference/runs/) endpoints. This section of the script runs the app with the batch you created as input, checks the status of the app run, and gets the results. ```python run = client.apps.runs.create(app_name=, owner=, batch_id=batch.id) # repeatedly check run status until run is complete status = client.apps.runs.status(run.id) while status.status == 'RUNNING': time.sleep(5) # polling interval in seconds status = client.apps.runs.status(run.id) # get app run results results = client.apps.runs.results(run.id) ``` ### Parameter reference | Parameter | Type | Required | Description | | ---------- | ---- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `app_name` | str | Yes | The name of the automation app to use to process the files in the batch. | | `owner` | str | No | The account that generated the app. • **For apps you created**: omit setting `owner`. • **For apps published by Instabase**: specify `instabase`. | For more information about customizing an app run, see the [run app](/api-sdk/api-reference/runs/run-app) endpoint. ## Complete script This script combines all the snippets from above and contains all the code needed to run an automation app using the SDK. The script performs these tasks: 1. [Initializes the API client](/api-sdk/using-api-sdk#initialize-the-sdk). 2. Creates a batch object and uploads files to the batch. 3. Runs an automation app using the batch as input. 4. Polls the app run status until the run is complete. 5. Returns app run results as a Python dictionary. See the [get run results](/api-sdk/api-reference/runs/get-run-results) endpoint for an example of app run results. ```python import os import time from aihub import AIHub # initialize the SDK client client = AIHub(api_root=, api_key=, ib_context=) # create a batch batch = client.batches.create(name=) # add files to the batch file_paths = [, ] for path in file_paths: with open(path, 'rb') as file: client.batches.add_file(batch_id=batch.id, file_name=os.path.basename(path), file=file) run = client.apps.runs.create(app_name=, owner=, batch_id=batch.id) # repeatedly check run status until run is complete status = client.apps.runs.status(run.id) while status.status == 'RUNNING': time.sleep(5) # polling interval in seconds status = client.apps.runs.status(run.id) # get app run results results = client.apps.runs.results(run.id) ``` ### Parameter reference | Value | Type | Required | Description | | ------------ | ---------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_root` | str | No | The root URL of your AI Hub API. For **organization accounts** • If your organization has a custom AI Hub domain, use your organization's root API URL, such as `https://my-org.instabase.com/api`. • If your organization doesn't have a custom AI Hub domain, omit setting `api_root`. | | `api_key` | str | Yes | Your API token. | | `ib_context` | str | No, but recommended | The value for the `IB-Context` header that the SDK includes with all API requests. Set to your organization ID. | | `name` | str | Yes | User-defined name of the batch. Maximum length is 255 characters. | | `file_paths` | list\[str] | Yes | Paths to one or more local files to upload to the batch. Each path is a separate string. All paths are collected in a list, even if there's only one path. | | `app_name` | str | Yes | The name of the automation app to use to process the files in the batch. | | `owner` | str | No | The account that generated the app. • **For apps you created**: omit setting `owner`. • **For apps published by Instabase**: specify `instabase`. |