Sign in

v2

latestOpenAPI 3.1.02026-08-06276982.8 KB
runs

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

</Tip>

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

post/v2/apps/runs

Headers

Authorizationstring required

Bearer HTTP authentication.

IB-Contextstring

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

Request body

app_namestring

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

app_idstring

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>

ownerstring

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_idinteger

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_dirstring

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

versionstring

Version of the app to use. If not specified, defaults to the latest production version.

output_workspacestring

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_dirstring

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.

Response

Run started successfully.

idstring

Run ID of the run.

status'CANCELLED' | 'COMPLETE' | 'FAILED' | 'PAUSED' | 'RUNNING' | 'STOPPED_AT_CHECKPOINT'

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_timestampinteger

When the run started, in Unix time nanoseconds.

finish_timestampinteger nullable

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

msgstring nullable

Message about the run.

batch_idinteger nullable

The batch ID used as input for this run.

input_dirstring nullable

The path of the input folder used for this run.

app_idstring nullable

The app ID of the app that was run.

deployment_idstring nullable

The deployment ID used for this run.

tagsstring[] nullable

List of string tags attached to this run.