Run app

POST

Run an app by its name or app ID. The input for the run can be a batch ID or an input file path.

Commercial & Enterprise

Running an 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. 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.

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 for details.

Request

This endpoint expects an object.
app_namestringOptional

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

app_idstringOptional

Required unless using app_name. The app ID of the AI Hub 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.
ownerstringOptional

The account that generated the app. If not specified, defaults to your AI Hub username.

For custom AI Hub apps belonging to you, accept the default. For public AI Hub 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. The output is saved to the default drive of the specified workspace. If not defined, the default is:

  • Community accounts: Runs in and saves to the personal workspace’s Instabase Drive (<USER-ID>/my-repo/Instabase Drive).

  • Organization accounts: Runs in and saves to the organization’s default drive (<ORGANIZATION-ID>/<USER-ID>/<default-drive>).

If this parameter is not specified, the results are sent to the user’s personal workspace. This can cause visibility problems in shared workspaces.

When making this call from a service account, you must specify a value for either output_workspace or output_dir.

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.

idstringOptional

Run ID of the run.

statusenumOptional

Status of the run.

start_timestamplongOptional

When the run started, in Unix time.

finish_timestamplongOptional

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

msgstringOptional

Message about the run.

Get run status