API referenceRuns

Run app

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> <span class="badge">Commercial & Enterprise</span> 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. For example, if the context is set to your community account, but the batch ID used as input for the run is stored in your organization, the call fails.</Note>

Authentication

AuthorizationBearer
Bearer HTTP authentication.

Headers

IB-ContextstringOptional
Specify whether to use your community account or organization account to complete the request. To use your community account, define as your user ID. To use your organization account, define as your organization ID. If unspecified, defaults to community account context. See [Authorization and context identification](/api-sdk/authorization#ib-context-header) 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 or null
Run ID of the run.
statusenum or null
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 or null
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.