# List conversations

> GET /v1/conversations

Conversations this key can reach, newest first. Use `order=changed` with `changed_after` to sync: oldest change first, and the last page's `next_cursor` is the place to ask again from later. Changes from the last minute wait for the next page. With `q`, only conversations whose transcript has those words, each with the passage that matched — which also needs `transcripts:read`, 30 a minute per key. Needs `conversations:read`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `order` | query | [Order](/reference/objects/Order) | No | `newest`, `oldest` or `changed`. |
| `agent_id` | query | string (uuid) or null | No |  |
| `project_id` | query | string (uuid) or null | No |  |
| `channel` | query | [Channel](/reference/objects/Channel) or null | No |  |
| `direction` | query | [Direction](/reference/objects/Direction) or null | No |  |
| `status` | query | array of [ConversationStatus](/reference/objects/ConversationStatus) or null | No | Repeat to ask for several. |
| `disposition` | query | [Disposition](/reference/objects/Disposition) or null | No |  |
| `outcome` | query | [Outcome](/reference/objects/Outcome) or null | No | The analysis's outcome. |
| `ended_by` | query | [EndedBy](/reference/objects/EndedBy) or null | No |  |
| `mode` | query | [ConversationMode](/reference/objects/ConversationMode) or null | No |  |
| `phone_number_id` | query | string (uuid) or null | No |  |
| `from_number` | query | string or null | No |  |
| `to_number` | query | string or null | No |  |
| `campaign_id` | query | string (uuid) or null | No |  |
| `external_id` | query | string or null | No | Your own id, as `POST /v1/calls` or `/v1/chats` sent it. |
| `created_after` | query | string (date-time) or null | No | Started at or after this time. |
| `created_before` | query | string (date-time) or null | No | Started before this time. |
| `changed_after` | query | string (date-time) or null | No | Changed at or after this time. |
| `changed_before` | query | string (date-time) or null | No | Changed before this time. |
| `limit` | query | integer | No | How many to return, 1 to 100. |
| `q` | query | string or null | No | Words that were said. A word also finds longer ones that start with it (`refund` finds `refunded`), a phrase in quotes is found as written, and `-word` leaves out the conversations that have it. Needs `transcripts:read`. |
| `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. |

## Answer

`200` with [ConversationList](/reference/objects/ConversationList).

## Errors

Every error is a [problem document](/errors) with a stable `code`.

| Status | When |
|---|---|
| `401` | The key is missing, mistyped, unknown, revoked or expired. |
| `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. |
| `422` | Validation Error |
| `429` | Too many requests for this key or its organization; see `Retry-After`. |
| `500` | Something went wrong on our side. Quote the `request_id` to support. |

## Examples

**curl**

```sh
#!/bin/sh
# List conversations
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"
```

**JavaScript**

```js
// List conversations
const response = await fetch("https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`,
  },
});
const answer = await response.json();
if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`);
console.log(answer);
```

**Python**

```python
# List conversations
# pip install httpx
import os

import httpx

response = httpx.get(
    "https://api.aigently.ai/v1/conversations",
    headers={
        "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}",
    },
    params={
        "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c",
        "status": "completed",
        "limit": 10,
    },
)
if response.is_error:
    raise SystemExit(response.text)
print(response.json())
```

**Go**

```go
// List conversations
package main

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

func main() {
	request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10", nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY"))
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	body, _ := io.ReadAll(response.Body)
	if response.StatusCode >= 400 {
		fmt.Fprintln(os.Stderr, string(body))
		os.Exit(1)
	}
	fmt.Println(string(body))
}
```

**Java**

```java
// List conversations
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10"))
            .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        // HTTP/1.1: on a plain-http address Java's default asks to upgrade, which not every
        // server allows.
        HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            System.err.println(response.body());
            System.exit(1);
        }
        System.out.println(response.body());
    }
}
```

**C#**

```csharp
// List conversations
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10")
{
};
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(body);
    return 1;
}
Console.WriteLine(body);
return 0;
```

**PHP**

```php
<?php
// List conversations
$curl = curl_init("https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"),
    ],
]);
$body = curl_exec($curl);
if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) {
    fwrite(STDERR, $body . "\n");
    exit(1);
}
echo $body, "\n";
```
**curl**

```sh
#!/bin/sh
# Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"
```

**JavaScript**

```js
// Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
const response = await fetch("https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`,
  },
});
const answer = await response.json();
if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`);
console.log(answer);
```

**Python**

```python
# Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
# pip install httpx
import os

import httpx

response = httpx.get(
    "https://api.aigently.ai/v1/conversations",
    headers={
        "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}",
    },
    params={
        "order": "changed",
        "changed_after": "2026-10-01T00:00:00Z",
    },
)
if response.is_error:
    raise SystemExit(response.text)
print(response.json())
```

**Go**

```go
// Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
package main

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

func main() {
	request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z", nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY"))
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	body, _ := io.ReadAll(response.Body)
	if response.StatusCode >= 400 {
		fmt.Fprintln(os.Stderr, string(body))
		os.Exit(1)
	}
	fmt.Println(string(body))
}
```

**Java**

```java
// Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z"))
            .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        // HTTP/1.1: on a plain-http address Java's default asks to upgrade, which not every
        // server allows.
        HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            System.err.println(response.body());
            System.exit(1);
        }
        System.out.println(response.body());
    }
}
```

**C#**

```csharp
// Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z")
{
};
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(body);
    return 1;
}
Console.WriteLine(body);
return 0;
```

**PHP**

```php
<?php
// Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
$curl = curl_init("https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"),
    ],
]);
$body = curl_exec($curl);
if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) {
    fwrite(STDERR, $body . "\n");
    exit(1);
}
echo $body, "\n";
```
**curl**

```sh
#!/bin/sh
# Find conversations by what was said. Each one comes with the passage that matched.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"
```

**JavaScript**

```js
// Find conversations by what was said. Each one comes with the passage that matched.
const response = await fetch("https://api.aigently.ai/v1/conversations?q=refund&limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`,
  },
});
const answer = await response.json();
if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`);
console.log(answer);
```

**Python**

```python
# Find conversations by what was said. Each one comes with the passage that matched.
# pip install httpx
import os

import httpx

response = httpx.get(
    "https://api.aigently.ai/v1/conversations",
    headers={
        "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}",
    },
    params={
        "q": "refund",
        "limit": 10,
    },
)
if response.is_error:
    raise SystemExit(response.text)
print(response.json())
```

**Go**

```go
// Find conversations by what was said. Each one comes with the passage that matched.
package main

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

func main() {
	request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?q=refund&limit=10", nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY"))
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	body, _ := io.ReadAll(response.Body)
	if response.StatusCode >= 400 {
		fmt.Fprintln(os.Stderr, string(body))
		os.Exit(1)
	}
	fmt.Println(string(body))
}
```

**Java**

```java
// Find conversations by what was said. Each one comes with the passage that matched.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations?q=refund&limit=10"))
            .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        // HTTP/1.1: on a plain-http address Java's default asks to upgrade, which not every
        // server allows.
        HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            System.err.println(response.body());
            System.exit(1);
        }
        System.out.println(response.body());
    }
}
```

**C#**

```csharp
// Find conversations by what was said. Each one comes with the passage that matched.
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.aigently.ai/v1/conversations?q=refund&limit=10")
{
};
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(body);
    return 1;
}
Console.WriteLine(body);
return 0;
```

**PHP**

```php
<?php
// Find conversations by what was said. Each one comes with the passage that matched.
$curl = curl_init("https://api.aigently.ai/v1/conversations?q=refund&limit=10");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"),
    ],
]);
$body = curl_exec($curl);
if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) {
    fwrite(STDERR, $body . "\n");
    exit(1);
}
echo $body, "\n";
```