> ## Documentation Index > Fetch the complete documentation index at: https://docs.minimo.it/llms.txt > Use this file to discover all available pages before exploring further. # List Threads > Inbox threads, pinned first then newest activity first, with the inbox filters and the tab counters A **thread** is the whole conversation with one contact: email, WhatsApp, SMS and Telegram together, the same threads your team sees in the inbox. See [Inbox](https://docs.minimo.it/product/inbox/introduction.md) for the concepts. ## Use Cases * **Find who needs a person**: `needsAttention=true` lists the threads where the AI handed over or is paused while the contact waits * **Build your own inbox view**: the same filters and tab counters as the app * **Look up a contact's thread**: `search` matches the contact's name, email or phone To search **what was written** in the messages, use [Search Threads](https://docs.minimo.it/api-reference/inbox/search-threads.md). ## Permissions The API key needs the **Inbox** permission (**Developer › API keys**). Every call is scoped to the key's workspace. `assigned=me` means the user who created the key; `counters.mine` is there when the key belongs to a user. ## Related * **[Get Thread](https://docs.minimo.it/api-reference/inbox/get-thread.md)**: read the messages of a thread * **MCP**: agents connected to Minimo's MCP server use `minimo_inbox_list-threads`, which returns the same objects ([Inbox for your AI agent](https://docs.minimo.it/product/inbox/ai-agent.md)) ## OpenAPI ````yaml get /public/v1/inbox/threads openapi: 3.1.0 info: title: API Documentation description: Documentation for transactional and subscribe APIs version: 1.0.0 servers: - url: https://app.minimo.it security: - bearerAuth: [] paths: /public/v1/inbox/threads: servers: - url: https://api.minimo.it get: summary: List inbox threads description: >- Inbox threads, pinned first then newest activity first, with the inbox filters and the tab counters. operationId: listInboxThreads parameters: - name: status in: query required: false description: Default `open`. schema: type: string enum: - open - closed - snoozed - all default: open - name: channel in: query required: false description: Only threads on this channel. schema: type: string enum: - whatsapp - email - sms - telegram - name: unread in: query required: false description: '`true` = only threads with unread messages.' schema: type: boolean - name: needsAttention in: query required: false description: >- `true` = a person must answer: the AI handed over, or it is paused while the contact waits. schema: type: boolean - name: assigned in: query required: false description: '`me` = the user who created the key.' schema: type: string enum: - any - me - unassigned default: any - name: search in: query required: false description: >- Contact's name, email or phone. To search what was written, use Search Threads. schema: type: string maxLength: 200 - name: page in: query required: false description: '' schema: type: integer minimum: 1 default: 1 - name: pageSize in: query required: false description: '' schema: type: integer minimum: 1 maximum: 50 default: 20 responses: '200': description: Threads, pagination and tab counters content: application/json: schema: type: object properties: data: type: object properties: threads: type: array items: $ref: '#/components/schemas/InboxThread' pagination: type: object properties: currentPage: type: integer nextPage: type: integer nullable: true prevPage: type: integer nullable: true totalPages: type: integer totalRecords: type: integer counters: type: object description: >- Thread counts per inbox tab. `mine` is there when the key belongs to a user. properties: open: type: integer closed: type: integer snoozed: type: integer unassigned: type: integer unread: type: integer needsTakeover: type: integer needsAttention: type: integer mine: type: integer example: data: threads: - threadId: 1234 status: open unreadMessages: 2 pinned: false channels: - whatsapp contact: contactId: 5678 name: Mario Rossi email: null phone: '393331234567' assignedTo: null needsHuman: true ai: state: active since: null snoozedUntil: null updatedAt: '2026-11-13T09:00:00.000Z' lastMessage: messageId: 90112 direction: inbound channel: whatsapp subject: null preview: Can I talk to a person? at: '2026-11-13T09:00:00.000Z' pagination: currentPage: 1 nextPage: null prevPage: null totalPages: 1 totalRecords: 1 counters: open: 27 closed: 2 snoozed: 2 unassigned: 26 unread: 3 needsTakeover: 3 needsAttention: 4 mine: 0 '400': description: '`INVALID_PARAMETERS`: a parameter of the wrong type or out of range.' content: application/json: schema: $ref: '#/components/schemas/InboxError' '401': description: Missing or invalid API key, or a key without the `Inbox` permission. security: - bearerAuth: [] x-codeSamples: - label: CLI lang: cURL source: |- curl --request GET \ --url 'https://api.minimo.it/public/v1/inbox/threads?needsAttention=true&pageSize=10' \ --header 'Authorization: Bearer {{BEARER_TOKEN}}' - lang: JavaScript source: >- const res = await fetch('https://api.minimo.it/public/v1/inbox/threads?needsAttention=true&pageSize=10', { method: 'GET', headers: { 'Authorization': 'Bearer {{BEARER_TOKEN}}', }, }); const { data } = await res.json(); console.log(data); - lang: Python source: |- import requests res = requests.get( 'https://api.minimo.it/public/v1/inbox/threads?needsAttention=true&pageSize=10', headers={'Authorization': 'Bearer {{BEARER_TOKEN}}'}, ) print(res.json()) components: schemas: InboxThread: type: object description: >- One conversation with one contact: email, WhatsApp, SMS and Telegram together. The MCP `minimo_inbox_*` tools return the same object. properties: threadId: type: integer example: 1234 status: type: string enum: - open - closed - snoozed unreadMessages: type: integer example: 2 pinned: type: boolean channels: type: array description: Channels this contact has used in the thread. items: type: string enum: - whatsapp - email - sms - telegram contact: type: object properties: contactId: type: integer example: 5678 name: type: string nullable: true example: Mario Rossi email: type: string nullable: true example: mario@example.com phone: type: string nullable: true example: '393331234567' assignedTo: type: object nullable: true description: The teammate the thread is assigned to, `null` if nobody. properties: userId: type: integer example: 42 name: type: string nullable: true example: Giulia Bianchi needsHuman: type: boolean description: The AI handed the thread over to a person. ai: type: object properties: state: type: string enum: - active - paused - disabled description: >- `active` = the AI answers. `paused` = a teammate replied or the AI handed over; the AI comes back after the assistant's pause time. `disabled` = off on this thread until it is turned on again. since: type: string format: date-time nullable: true description: When the AI paused (`paused` only). snoozedUntil: type: string format: date-time nullable: true updatedAt: type: string format: date-time lastMessage: type: object nullable: true properties: messageId: type: integer example: 90112 direction: type: string enum: - inbound - outbound description: >- `inbound` = from the contact, `outbound` = from you, your team or your AI. channel: type: string enum: - whatsapp - email - sms - telegram subject: type: string nullable: true description: Email only. preview: type: string description: The text on one line, up to 280 characters. at: type: string format: date-time InboxError: type: object description: >- `message` is the code, `userMessage` a sentence you can show to a person. properties: status: type: string example: FAIL message: type: string example: WHATSAPP_WINDOW_CLOSED userMessage: type: string example: >- WhatsApp allows free text only within 24 hours of the contact's last WhatsApp message. Send an approved template instead. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: mn-API_CLIENT_ID-API_KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.