> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.jelliu.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.jelliu.co/_mcp/server.

# List conversations

GET https://api.jelliu.co/api/conversations

Returns one page of the workspace's **active** conversations across every text channel.
Closed conversations are not listed. Fetch a closed one directly with
`GET /api/conversations/{conversationId}`. Each row carries the conversation columns plus
the contact's name, phone and lead status, the agent's name, a 160-character preview of the
last message and a lead `qualification` score.

**Ordering and filtering.** By default rows are ordered by `updated_at` descending (most
recent activity first). With `needsHuman=waiting` only threads where the agent asked for a
person and nobody has resolved it yet are returned, ordered by `needs_human_at`
**ascending**, so the person who has waited longest comes first.

**Pagination.** Page-number pagination with `page` and `limit`. `total` is the number of
matching conversations across all pages. `needsHumanWaiting` is the workspace-wide count of
threads waiting for a person, whatever page or filter you asked for. Invalid values are
never rejected: a non-numeric or zero `page` becomes `1`, a non-numeric or zero `limit`
becomes `50`, and a `limit` above 100 is clamped to `100`.

**Consistency.** Pages are cached for up to 30 seconds. An operator reply sent through
`POST /api/conversations/{conversationId}/messages` clears the cache immediately.
`needsHumanWaiting` is never cached.

**Access**

* **Required scope:** `read` (or `write`).
* **Rate limit:** General API — 120 requests/min per workspace (Starter), 200 (Growth), 300 (Business), 600 (Enterprise). See [Rate limits](/rate-limits).
* **Plan:** Available on every plan.

Reference: https://developer.jelliu.co/api-reference/conversations/get-conversations

## Authentication

- `Authorization` header (bearer token, required) — Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

## Request

### Query parameters

- `page` (integer, optional, default: 1) — 1-indexed page number. Non-numeric or values below 1 are treated as `1`.
- `limit` (integer, optional, default: 50) — Conversations per page. Values above 100 are clamped to 100; non-numeric or values below 1 fall back to 50.
- `needsHuman` (enum, optional) — Pass `waiting` to list only threads where the agent asked for a person and it is not resolved yet, oldest wait first. Any other value is ignored and the normal list is returned.
  - Allowed values: `waiting`

## Response

### 200

One page of conversations.

- `data` (object, required)
  - `conversations` (list of object, required)
    - `id` (string, optional) — Unique id of the conversation.
    - `tenant_id` (string, optional) — Workspace that owns the conversation.
    - `agent_id` (string, optional, nullable) — Agent that answers the thread. `null` when none is bound, for example a conversation started from the dashboard before any reply.
    - `contact_id` (string, optional, nullable) — Contact on the other side. `null` for anonymous webchat visitors who never identified.
    - `channel` (enum, optional) — Channel of the thread. - `whatsapp`: WhatsApp. - `email`: email through the workspace's connected mailbox. - `webchat`: the website widget. - `instagram`: Instagram direct messages. - `messenger`: Facebook Messenger.
      - Allowed values: `whatsapp`, `email`, `webchat`, `instagram`, `messenger`
    - `external_id` (string, optional, nullable) — Provider-side thread key used to route inbound messages into this conversation (e.g. `webchat_<visitorId>`).
    - `status` (enum, optional) — - `active`: the thread is open and listed by `GET /api/conversations`. - `closed`: closed by an operator, a deleted agent or an exhausted budget. The next inbound message reopens it.
      - Allowed values: `active`, `closed`
    - `metadata` (map from string to any, optional, nullable) — Free-form channel data attached to the thread. Usually `null`.
    - `created_at` (datetime, optional) — When the conversation was created.
    - `updated_at` (datetime, optional) — Last change to the row (reopen, close, binding, human-help flag). The inbox is ordered by it.
    - `closed_at` (datetime, optional, nullable) — When the conversation was last closed. `null` while active.
    - `last_inbound_at` (datetime, optional, nullable) — When the contact last wrote on this thread. On WhatsApp, Instagram and Messenger this drives the 24-hour window.
    - `needs_human_at` (datetime, optional, nullable) — When the agent asked for a person. `null` means it never did.
    - `needs_human_reason` (string, optional, nullable) — What the agent could not do, written for an operator (up to 400 characters). Never shown to the contact.
    - `needs_human_resolved_at` (datetime, optional, nullable) — When a person marked the request handled. `null` while waiting, or when there was no request.
    - `summary` (string, optional, nullable) — Two or three sentences summarising the thread, written by the model that handled it.
    - `sentiment_score` (double, optional, nullable) — Overall sentiment from -1 to 1. `null` means not analysed, which is not the same as neutral.
    - `frustration_score` (double, optional, nullable) — How frustrated the contact got, from 0 to 1, aggregated over every scored turn. `null` means not measured.
    - `sentiment_low` (double, optional, nullable) — Sentiment of the worst single contact turn, from -1 to 1. `null` means not measured.
    - `outcome` (enum, optional) — Analysis verdict. `null` until analysed. - `success`: the conversation achieved the agent's goal. - `failure`: it did not. - `unknown`: the analysis could not tell.
      - Allowed values: `success`, `failure`, `unknown`
    - `evaluation_criteria_results` (map from string to any, optional, nullable) — Result of each evaluation criterion configured on the agent, keyed by criterion id, as `{ result, rationale }`.
    - `data_collection_results` (map from string to any, optional, nullable) — Values extracted by the agent's data-collection fields, keyed by field id, as `{ value, rationale }`. Feeds `qualification`.
    - `analysis_fetched_at` (datetime, optional, nullable) — When the analysis was last fetched successfully. `null` means never.
    - `analysis_attempts` (integer, optional) — How many times fetching the analysis was attempted. The background sweep gives up after five.
    - `cost_credits` (double, optional, nullable) — Voice-engine credits the thread consumed. `null` when not measured.
    - `cost_usd` (string, optional, nullable) — Cost in US dollars, as a decimal serialized as a string. `null` when not measured.
    - `termination_reason` (string, optional, nullable) — Why the last voice-engine session ended, as reported by the voice engine (up to 160 characters).
    - `main_language` (string, optional, nullable) — Main language detected in the thread, lower-case (e.g. `es`).
    - `call_success_score` (double, optional, nullable) — Success score reported by the analysis, when the provider supplies one.
    - `tool_call_count` (integer, optional, nullable) — Tool calls the agent made. `null` means not measured; `0` means measured and none were made.
    - `mcp_call_count` (integer, optional, nullable) — How many of those tool calls went to MCP servers. `null` means not measured.
    - `rag_lookup_count` (integer, optional, nullable) — Knowledge-base lookups made during the thread. `null` means not measured.
    - `tool_result_bytes` (string, optional, nullable) — Total size of tool results fed back to the model, as a big integer serialized as a string.
    - `contact_name` (string, optional, nullable) — Name of the contact, joined from the contact record.
    - `contact_phone` (string, optional, nullable) — Contact phone number. For webchat or email-only contacts, their email address instead.
    - `contact_status` (string, optional, nullable) — Lead status of the contact (a free string on the contact record; these are the values the platform writes). `null` for anonymous threads. - `pending`: not worked yet. - `called`: reached. - `converted`: the lead converted. - `failed`: attempts failed. - `dnc`: do not contact. - `invalid`: unusable contact data.
    - `agent_name` (string, optional, nullable) — Name of the bound agent, joined from the agent record.
    - `last_message` (string, optional, nullable) — Preview of the last message, delimiter tags stripped, at most 160 characters.
    - `last_message_at` (datetime, optional, nullable) — When the last message was stored. `null` for a thread with no messages.
    - `last_message_role` (enum, optional) — Who wrote the last message. `user` with no reply after it means the contact is waiting for an answer. - `user`: the contact. - `agent`: the AI agent or a person on the team.
      - Allowed values: `user`, `agent`
    - `qualification` (object, optional, nullable) — Lead score derived from `data_collection_results` and `outcome`, the same scoring used for calls. `null` when there is nothing to score.
      - `score` (integer, optional, nullable) — Lead score from 0 to 100. `null` when the thread gave nothing to score; never a default.
      - `interest` (enum, optional) — Interest level detected: `high`, `medium` or `low`.
        - Allowed values: `high`, `medium`, `low`
      - `answered` (boolean, optional, nullable) — Whether a real person engaged.
      - `next_step` (string, optional, nullable) — The concrete commitment agreed, if any.
      - `objections` (list of string, optional) — Objections the contact raised.
      - `reasons` (list of string, optional) — Signals that fed the score, so the number can be explained.
  - `total` (integer, required) — Total matching conversations across all pages.
  - `page` (integer, required) — The page returned, after clamping.
  - `limit` (integer, required) — The page size used, after clamping.
  - `needsHumanWaiting` (integer, required) — Workspace-wide count of threads waiting for a person, independent of the page and filter.

## Errors

### 401 Unauthorized Error

No usable credential. Either the `Authorization` header is missing or is not a well-formed `Bearer jl_…` key, or the key is unknown, revoked or expired. Do not retry with the same key. See [Authentication](/authentication#401-unauthorized).

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

### 403 Forbidden Error

The API key has neither the `read` nor the `write` scope, or the workspace is suspended.

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

### 429 Too Many Requests Error

General API limit exceeded for this minute.

- `error` (object, required) — The error object. Always has `code` and `message`.
  - `code` (string, required) — Stable machine-readable error code (for example `VALIDATION_FAILED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BILLING_ERROR`, `COMPLIANCE_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`). Switch on this, not on `message`. See [Errors](/errors).
  - `message` (string, required) — Human-readable explanation. English or Spanish depending on the route; may change without notice.
  - `details` (object or list of object, optional) — Present on `VALIDATION_FAILED` only. Its shape depends on how the route validates: * a field map, either Zod's `flatten()` output (`{ "formErrors": [], "fieldErrors": { "name": ["..."] } }`) or just its `fieldErrors` part (`{ "name": ["..."] }`); * an issue list, where each issue has at least `path`, `message` and `code`. `path` is a dot-separated string on routes that let the schema throw, and an array of keys on routes that forward Zod's raw issues (those also carry Zod's extra issue fields).
    - Field map
      - `formErrors` (list of string, optional)
      - `fieldErrors` (map from string to list of string, optional)
  - `metadata` (map from string to any, optional) — Structured detail exposed for a small allowlist of codes only — for example `BILLING_ERROR` carries `limit`, `current` and `tier` (resource caps) or `tier` and `feature` (feature gates).

## Examples

**Response**

```json
{
  "data": {
    "conversations": [
      {
        "id": "3f1c2a9e-5b7d-4e8f-9a01-2c3d4e5f6a7b",
        "tenant_id": "9b2e4d1a-7c3f-4a8e-b5d6-1f0e2c3a4b5d",
        "agent_id": "c4a7e2f1-8b3d-4e6a-9f0c-5d2b1a3e7c9f",
        "contact_id": "7d6c5b4a-3f2e-4d1c-8b9a-0e1f2a3b4c5d",
        "channel": "whatsapp",
        "external_id": "wa_5e8a1c2d-4b6f-4a3e-9d7c-0b1a2f3e4d5c_+573001234567",
        "status": "active",
        "metadata": {},
        "created_at": "2026-09-12T14:02:11.000Z",
        "updated_at": "2026-09-14T16:45:03.000Z",
        "closed_at": null,
        "last_inbound_at": "2026-09-14T16:44:58.000Z",
        "needs_human_at": "2026-09-14T16:45:02.000Z",
        "needs_human_reason": "El cliente pide un descuento por volumen que el agente no puede aprobar.",
        "needs_human_resolved_at": null,
        "summary": "María pregunta por precios para 40 unidades y pide un descuento por volumen.",
        "sentiment_score": 0.35,
        "frustration_score": 0.1,
        "sentiment_low": -0.2,
        "outcome": "unknown",
        "evaluation_criteria_results": {},
        "data_collection_results": {
          "interest_level": {
            "rationale": "Pidió cotización formal.",
            "value": "high"
          }
        },
        "analysis_fetched_at": "2026-09-14T16:50:00.000Z",
        "analysis_attempts": 1,
        "cost_credits": 412,
        "cost_usd": "0.0132",
        "termination_reason": null,
        "main_language": "es",
        "call_success_score": null,
        "tool_call_count": 2,
        "mcp_call_count": 0,
        "rag_lookup_count": 1,
        "tool_result_bytes": "1840",
        "contact_name": "María Fernanda Rojas",
        "contact_phone": "+573001234567",
        "contact_status": "pending",
        "agent_name": "Asesora comercial",
        "last_message": "¿Me pueden hacer un descuento si compro 40 unidades?",
        "last_message_at": "2026-09-14T16:44:58.000Z",
        "last_message_role": "user",
        "qualification": {
          "score": 70,
          "interest": "high",
          "answered": true,
          "next_step": null,
          "objections": [
            "precio"
          ],
          "reasons": [
            "interest: high"
          ]
        }
      }
    ],
    "total": 137,
    "page": 1,
    "limit": 25,
    "needsHumanWaiting": 2
  }
}
```

**SDK Code**

```python Conversations_getConversations_example
import requests

url = "https://api.jelliu.co/api/conversations"

querystring = {"limit":"25","needsHuman":"waiting","page":"1"}

headers = {"Authorization": "Bearer <token>"}

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

print(response.json())
```

```javascript Conversations_getConversations_example
const url = 'https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

```go Conversations_getConversations_example
package main

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

func main() {

	url := "https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

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

}
```

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

url = URI("https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

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

HttpResponse<String> response = Unirest.get("https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp Conversations_getConversations_example
using RestSharp;

var client = new RestClient("https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Conversations_getConversations_example
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.jelliu.co/api/conversations?limit=25&needsHuman=waiting&page=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```