List Org Conversations

curl --request GET \
  --url https://api.example.com/api/organizations/{org_id}/conversations \
  --header 'X-Access-Token: <api-key>'

import requests

url = "https://api.example.com/api/organizations/{org_id}/conversations"

headers = {"X-Access-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.example.com/api/organizations/{org_id}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/organizations/{org_id}/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.example.com/api/organizations/{org_id}/conversations"

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

	req.Header.Add("X-Access-Token", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/organizations/{org_id}/conversations")

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

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

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

{
  "items": [
    {
      "id": "<string>",
      "user_id": "<string>",
      "title": "<string>",
      "llm_model": "<string>",
      "agent_kind": "openhands",
      "user_email": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "sandbox_id": "<string>",
      "sandbox_status": "<string>",
      "runtime_url": "<string>",
      "execution_status": "<string>",
      "selected_repository": "<string>",
      "selected_branch": "<string>",
      "git_provider": "<string>",
      "trigger": "<string>",
      "pr_number": [
        123
      ],
      "pr_merged": true,
      "tags": {},
      "accumulated_cost": 0,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0
    }
  ],
  "total_items": 0,
  "page": 1,
  "per_page": 100,
  "total_pages": 0,
  "pagination_accurate": true
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Orgs

List Org Conversations

List all conversations for an organization.

This endpoint returns a paginated list of all conversations within an organization, including details about each conversation such as the creator, timestamps, and metrics.

Access Control: Requires VIEW_ORG_CONVERSATIONS permission (Admin or Owner role).

Args: org_id: Organization UUID search: Search text matching conversation name, creator name, email, or sandbox ID sort_by: Field to sort by (created_at, updated_at, llm_model, accumulated_cost, title) sort_order: Sort order (desc or asc) execution_status: Filter by execution status (idle, running, paused, finished, error, stuck) sandbox_status: Filter by sandbox status (STARTING, RUNNING, PAUSED, ERROR, MISSING) time_window: Time window filter (all, 7d, 30d, 90d) page: Page number (1-indexed) per_page: Items per page (1-100) include_sub_conversations: If True, include sub-conversations in results user_id: Authenticated user ID (injected by require_permission dependency) service: OrgConversationService instance

Returns: OrgConversationPage: Paginated list of conversations with total count

Raises: HTTPException: 401 if user is not authenticated HTTPException: 403 if user lacks VIEW_ORG_CONVERSATIONS permission HTTPException: 500 if retrieval fails

GET

api

organizations

{org_id}

conversations

List Org Conversations

curl --request GET \
  --url https://api.example.com/api/organizations/{org_id}/conversations \
  --header 'X-Access-Token: <api-key>'

import requests

url = "https://api.example.com/api/organizations/{org_id}/conversations"

headers = {"X-Access-Token": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Access-Token': '<api-key>'}};

fetch('https://api.example.com/api/organizations/{org_id}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/organizations/{org_id}/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Access-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.example.com/api/organizations/{org_id}/conversations"

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

	req.Header.Add("X-Access-Token", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/organizations/{org_id}/conversations")

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

request = Net::HTTP::Get.new(url)
request["X-Access-Token"] = '<api-key>'

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

{
  "items": [
    {
      "id": "<string>",
      "user_id": "<string>",
      "title": "<string>",
      "llm_model": "<string>",
      "agent_kind": "openhands",
      "user_email": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "sandbox_id": "<string>",
      "sandbox_status": "<string>",
      "runtime_url": "<string>",
      "execution_status": "<string>",
      "selected_repository": "<string>",
      "selected_branch": "<string>",
      "git_provider": "<string>",
      "trigger": "<string>",
      "pr_number": [
        123
      ],
      "pr_merged": true,
      "tags": {},
      "accumulated_cost": 0,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0
    }
  ],
  "total_items": 0,
  "page": 1,
  "per_page": 100,
  "total_pages": 0,
  "pagination_accurate": true
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

X-Access-Token

string

header

required

Headers

X-Org-Id

string | null

Path Parameters

org_id

string<uuid> | null

required

Query Parameters

string | null

sort_by

string

default:updated_at

Options: created_at, updated_at, llm_model, accumulated_cost, title

sort_order

string

default:desc

Options: desc (default), asc

execution_status

string[] | null

Comma-separated list: idle, running, paused, finished, error, stuck

sandbox_status

string | null

Filter by sandbox status: STARTING, RUNNING, PAUSED, ERROR, MISSING. Note: when filtering by sandbox_status, total_items reflects the unfiltered count since the filter is applied post-query. This may result in pagination showing fewer items per page than expected.

time_window

string | null

Options: all, 7d, 30d, 90d

page

integer

default:1

Required range: x >= 1

per_page

integer

default:20

Required range: 1 <= x <= 100

include_sub_conversations

boolean

default:false

Response

Successful Response

Paginated response for organization conversations.

items

OrgConversationResponse · object[]

required

Show child attributes

total_items

integer

default:0

page

integer

default:1

per_page

integer

default:100

total_pages

integer

default:0

pagination_accurate

boolean

default:true

OpenHands Cloud

Settings

Integrations

Cloud API

Organizations

List Org Conversations

Authorizations

Headers

Path Parameters

Query Parameters

Response