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

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.