> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.instabase.com/api-sdk/api-reference/runs/list-runs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.instabase.com/_mcp/server.

# List runs

GET https://aihub.instabase.com/api/v2/apps/runs

Return a list of runs. Use query parameters to filter results.

Reference: https://docs.instabase.com/api-sdk/api-reference/runs/list-runs

## Authentication

- `Authorization` header (bearer token, required) — Bearer HTTP authentication.

## Request

### Query parameters

- `app_id` (string, optional) — Filter runs by app ID.
- `app_name` (string, optional) — Filter runs by app name.
- `deployment_id` (string, optional) — Filter runs by deployment ID.
- `username` (string, optional) — Filter runs initiated by the specified user (username).
- `run_id` (string, optional) — Filter specific run by run ID.
- `status` (list of string, optional) — Filter jobs by status, such as COMPLETE, RUNNING, or FAILED.
- `output_workspaces` (list of string, optional) — Filter runs by the run's output workspace. By default, all runs across all workspaces you have access to are returned, use this query parameter to filter by specific workspace names. You must have access to the named workspaces.
- `from_timestamp` (integer, optional) — Filter runs starting from this timestamp. Timestamp in Unix time in seconds. Defaults to 24 hours before the current time.
- `to_timestamp` (integer, optional) — Filter runs up to this timestamp. Timestamp in Unix time in seconds. Defaults to the current time.
- `limit` (integer, optional) — Number of results to return.
- `offset` (integer, optional) — Offset of the first result to return.
- `sort_by` (enum, optional) — Field to sort results by.
  - Allowed values: `start_timestamp`, `status`
- `order` (enum, optional) — Order of sorting, such as ASCENDING or DESCENDING.
  - Allowed values: `ASCENDING`, `DESCENDING`

### Headers

- `IB-Context` (string, optional) — Typically your organization ID. See [Authorization and context identification](/api-sdk/authorization#ib-context-header) for details.

## Response

### 200

A list of all runs.

- `runs` (list of run, optional)

## Types

### run

- `id` (string, optional) — Run ID of the run.
- `status` (enum, optional) — 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
  - Allowed values: `CANCELLED`, `COMPLETE`, `FAILED`, `PAUSED`, `RUNNING`, `STOPPED_AT_CHECKPOINT`
- `start_timestamp` (long, optional) — When the run started, in Unix time nanoseconds.
- `finish_timestamp` (long, optional, nullable) — When the run finished, in Unix time nanoseconds. `null` if run is still in progress.
- `msg` (string, optional, nullable) — Message about the run.
- `batch_id` (integer, optional, nullable) — The batch ID used as input for this run.
- `input_dir` (string, optional, nullable) — The path of the input folder used for this run.
- `app_id` (string, optional, nullable) — The app ID of the app that was run.
- `deployment_id` (string, optional, nullable) — The deployment ID used for this run.
- `tags` (list of string, optional, nullable) — List of string tags attached to this run.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "runs": [
    {
      "id": "run_9f8b7c6d5e4a3b2c1d0e",
      "status": "CANCELLED",
      "start_timestamp": 1685606400000000000,
      "finish_timestamp": 1685608200000000000,
      "msg": "User cancelled the run due to incorrect input parameters.",
      "batch_id": 42,
      "input_dir": "/data/input/batch_42",
      "app_id": "app_1234567890abcdef",
      "deployment_id": "deploy_0987654321fedcba",
      "tags": [
        "urgent",
        "test-run"
      ]
    }
  ]
}
```

**SDK Code**

```python with SDK
from aihub import AIHub

client = AIHub(
    api_root="https://aihub.instabase.com/api",
    api_key="abcdefghijklmnopqrst1234567890",
    ib_context="john.doe_acme.com"
)

response = client.apps.runs.list()

print(f"third run ID: {response.runs[2].id}")  # 0-based indexing

```

```python without SDK
import requests

url = "https://aihub.instabase.com/api/v2/apps/runs"

headers = {
    "Authorization": "Bearer abcdefghijklmnopqrst1234567890",
    "IB-Context": "john.doe_acme.com"
}

# make the GET request
response = requests.get(url, headers=headers)

# handle the response
if response.status_code == 200:
    # the next line assumes the call returned at least 3 runs
    print(f"third run ID: {response.json()['runs'][2]['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

```

```javascript
const url = 'https://aihub.instabase.com/api/v2/apps/runs';
const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://aihub.instabase.com/api/v2/apps/runs"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://aihub.instabase.com/api/v2/apps/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://aihub.instabase.com/api/v2/apps/runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://aihub.instabase.com/api/v2/apps/runs', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://aihub.instabase.com/api/v2/apps/runs");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://aihub.instabase.com/api/v2/apps/runs")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```