For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Logo
AI Hub
OverviewApp editorFlow editorAdminAPI & SDK
OverviewApp editorFlow editorAdminAPI & SDK
  • Overview
    • Using the API and SDK
    • Authorization
    • Response statuses
  • API & SDK guides
    • Run automation apps by SDK
  • API reference
      • POSTRun deployment
      • POSTRun app
      • GETGet run status
      • GETGet run results
      • GETList runs
      • DELDelete run
      • Specifying file paths
  • Legacy APIs
    • Job status
    • Run apps
    • Run results
    • Mount
AI Hub
API referenceRuns

Run app

POST
https://aihub.instabase.com/api/v2/apps/runs
POST
/api/v2/apps/runs
$curl "${API_ROOT}/v2/apps/runs" \
>  -H "Authorization: Bearer ${API_TOKEN}" \
>  -H "IB-Context: ${IB_CONTEXT}" \
>  -H "Content-Type: application/json" \
>  -d '{
>        "batch_id": <BATCH-ID>,
>        "app_name": "<APP-NAME>"
>      }'
200Successful
1{
2  "id": "a3f1c9d2-4b7e-4f8a-9c3d-2e5b7f6a8d9e",
3  "status": "RUNNING",
4  "start_timestamp": 1685600000000000000,
5  "finish_timestamp": 0,
6  "msg": "Run initiated successfully.",
7  "batch_id": 98765,
8  "input_dir": "/connected_drive/projects/input_data",
9  "app_id": "528c36e8-ac5b-490d-a41b-7eec9c404b87",
10  "deployment_id": "d4f7e8a9-b123-4c56-8d9e-0f1a2b3c4d5e",
11  "tags": [
12    "invoice-processing",
13    "priority-high"
14  ]
15}
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>
Was this page helpful?
Previous

Get run status

Next
Built with

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.

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 to decide if you’d rather use the Run deployment API operation.

Any specified input or output is validated against the context set by the IB-Context header.

Authentication

AuthorizationBearer
Bearer HTTP authentication.

Headers

IB-ContextstringOptional

Typically your organization ID. See Authorization and context identification for details.

Request

This endpoint expects an object.
app_namestringOptional

Required unless using app_id. The name of the app to run.

app_idstringOptional
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>
ownerstringOptional

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_idintegerOptional

Required unless using input_dir. The batch ID of a batch created with the Batches endpoint. All files uploaded to the batch are used as input for the run.

input_dirstringOptional

Required unless using batch_id. The path of the input folder in a connected drive or Instabase Drive. See Specifying file paths.

versionstringOptional
Version of the app to use. If not specified, defaults to the latest production version.
output_workspacestringOptional
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_dirstringOptional

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.

settingsobjectOptional
JSON object containing settings for the app run.

Response

Run started successfully.
idstring
Run ID of the run.
statusenum

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_timestamplong
When the run started, in Unix time nanoseconds.
finish_timestamplong or null

When the run finished, in Unix time nanoseconds. null if run is still in progress.

msgstring or null
Message about the run.
batch_idinteger or null
The batch ID used as input for this run.
input_dirstring or null
The path of the input folder used for this run.
app_idstring or null
The app ID of the app that was run.
deployment_idstring or null
The deployment ID used for this run.
tagslist of strings or null
List of string tags attached to this run.

Required unless using app_name. The app ID of the app to run.

You can find an app ID in the app URL, such as https://aihub.instabase.com/hub/apps/528c36e8-ac5b-490d-a41b-7eec9c404b87.

The workspace in which to run the app. Output saves to the specified workspace. If not defined, the default is your personal workspace.

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.