> ## Documentation Index > Fetch the complete documentation index at: https://docs.reachhunt.ai/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Returns the one-to-one conversations in your workspace, across every connected account or for one. Open conversations are returned unless you change `scope`. Paged with a cursor. ## OpenAPI ````yaml /openapi.json get /conversations openapi: 3.1.0 info: title: ReachHunt API version: 1.0.0 description: >- The ReachHunt API gives your own apps and scripts programmatic access to your workspace: accounts, campaigns, lead lists, conversations, messages, tags and statuses. Send your API key in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. The key decides the workspace, so no path or parameter names one. Every response has the same envelope: `{ "status": true, "data": ..., "error": null }`. servers: - url: https://api.reachhunt.ai/api/v1 description: Production security: [] tags: - name: Workspaces description: Your workspace and the people in it. - name: Accounts description: The X and LinkedIn accounts you connected. - name: Analytics description: Activity over time. - name: Credits description: AI credits and how they were used. - name: Campaigns description: Outreach that messages your leads step by step. - name: Agents description: AI agents that reply to your leads. - name: Tags description: Labels you put on conversations. - name: Statuses description: Pipeline stages you put conversations in. - name: Leads description: The people in your lead lists. - name: Lead lists description: Lists of people you collect to message. - name: Conversations description: The conversations in your inbox. - name: Messages description: The messages in a conversation. - name: Conversation details description: Your team's record of the person in a conversation. - name: Internal notes description: Notes only your team sees. - name: Scheduled messages description: Messages set to send later. - name: Templates description: Saved messages you can reuse. - name: Webhook events description: What each event sends. paths: /conversations: get: tags: - Conversations summary: List conversations description: >- Returns the one-to-one conversations in your workspace, across every connected account or for one. Open conversations are returned unless you change `scope`. Paged with a cursor. operationId: conversations.list parameters: - name: accountId in: query required: false description: >- Only conversations of this connected account. Leave it out for all accounts. schema: type: string - name: search in: query required: false description: >- Text to look for in the person's name, in their handle, and in the last message. schema: type: string - name: scope in: query required: false description: >- Which conversations to return. - `all`: open conversations. - `unread`: open conversations with unread messages. - `needs_reply`: open conversations where the other person wrote last. - `pending`: open conversations where you wrote last. - `closed`: closed conversations. - `any`: open and closed. Defaults to `all`. schema: type: string enum: - all - unread - needs_reply - pending - closed - any - name: sort in: query required: false description: Order by the time of the last message. Defaults to `newest`. schema: type: string enum: - newest - oldest - name: tagId in: query required: false description: >- Only conversations with this tag. Repeat the parameter to match several tags. style: form explode: true schema: type: array items: type: string - name: statusId in: query required: false description: >- Only conversations in this status. Repeat the parameter to match several statuses. style: form explode: true schema: type: array items: type: string - name: limit in: query required: false description: How many items to return, from 1 to 100. Defaults to `50`. schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false description: >- `nextCursor` from the previous page. A cursor only works with the filters it was issued for. schema: type: string responses: '200': description: 'OK. Check `status`: errors the API handles itself also return 200.' content: application/json: schema: type: object required: - status - data - error properties: status: type: boolean description: '`true` when the request succeeded.' data: type: object required: - items - total - nextCursor - syncedAt - sources - isStale properties: items: type: array items: $ref: '#/components/schemas/Conversation' total: type: integer description: How many conversations match, across all pages. examples: - 128 nextCursor: type: - string - 'null' description: >- Pass it as `cursor` to read the next page. `null` on the last page. examples: - eyJvIjoiMTc5NjQ4MDAwMDAwMCJ9 syncedAt: type: - string - 'null' format: date-time description: >- When the conversations were last refreshed from X and LinkedIn, in ISO 8601 UTC. `null` until a refresh has finished. examples: - '2026-10-17T14:06:00.000Z' sources: type: array description: Where each account is in loading its conversations. items: type: object properties: accountId: type: string platform: $ref: '#/components/schemas/Platform' walk: type: - string - 'null' description: How far the account's history has been loaded. isStale: type: boolean description: Always `false`. Kept for older clients. error: type: 'null' description: Always `null` on success. example: status: true data: items: - conversationId: '1876543210987654321:1900000000000000001' accountId: 4f1c9a2e-6b7d-4c3a-9e51-0a8b7c6d5e4f platform: x type: one_to_one participantCount: 2 participants: - platform: x platformId: '1876543210987654321' userName: janedoe name: Jane Doe url: https://x.com/janedoe profilePicture: https://example.com/avatars/janedoe.jpg headline: null canDm: true isVerified: false followers: 1280 following: 340 location: Berlin description: Growth, partnerships and outbound. peerUnavailable: false tags: - id: 7c1f0c52-6d1a-4a49-9a63-2b3c4d5e6f70 label: Hot lead color: '#e24c5d' statusId: b8d1f6f4-3a52-4f3a-8f0b-0c2f6a9d1e11 valuation: 1500 assigneeId: null readUpTo: '1900000000000000100' peerReadUpTo: '1900000000000000100' hasUnread: true unreadCount: 1 isClosed: false isDraft: false sendTyping: null lastMessage: text: Thanks, sounds good. Send the details over. fromMe: false seqId: '1900000000000000123' createdAt: '2026-10-17T14:05:00.000Z' attachmentCount: 0 attachmentType: null seen: null total: 128 nextCursor: eyJvIjoiMTc5NjQ4MDAwMDAwMCJ9 syncedAt: '2026-10-17T14:06:00.000Z' sources: - accountId: 4f1c9a2e-6b7d-4c3a-9e51-0a8b7c6d5e4f platform: x walk: done isStale: false error: null '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PlanRequired' '500': $ref: '#/components/responses/ServerError' security: - bearerAuth: [] components: schemas: Conversation: type: object description: One conversation between a connected account and one person. required: - conversationId - accountId - platform - type - participantCount - participants - peerUnavailable - tags - statusId - valuation - assigneeId - readUpTo - peerReadUpTo - hasUnread - unreadCount - isClosed - isDraft - sendTyping - lastMessage properties: conversationId: type: string description: 'The conversation ID. URL-encode it in paths: X IDs contain `:`.' examples: - '1876543210987654321:1900000000000000001' accountId: type: string description: The connected account the conversation belongs to. examples: - 4f1c9a2e-6b7d-4c3a-9e51-0a8b7c6d5e4f platform: $ref: '#/components/schemas/Platform' type: type: string enum: - one_to_one description: Always `one_to_one`. Group chats are not listed. examples: - one_to_one participantCount: type: integer description: >- How many people are in the conversation, the connected account included. examples: - 2 participants: type: array description: The other people in the conversation. items: $ref: '#/components/schemas/Participant' peerUnavailable: type: boolean description: >- `true` when the other person's profile can no longer be loaded, for example after they deleted their account. examples: - false tags: type: array description: The tags on this conversation. items: $ref: '#/components/schemas/Tag' statusId: type: - string - 'null' description: >- The ID of the status this conversation is in. `null` when it has none. examples: - b8d1f6f4-3a52-4f3a-8f0b-0c2f6a9d1e11 valuation: type: - number - 'null' description: The deal value you set for this person. `null` when none is set. examples: - 1500 assigneeId: type: - string - 'null' description: The ID of the teammate it is assigned to. `null` when unassigned. examples: - null readUpTo: type: - string - 'null' description: Marker of the last message you have read. examples: - '1900000000000000123' peerReadUpTo: type: - string - 'null' description: Marker of the last message the other person has read. examples: - '1900000000000000100' hasUnread: type: boolean description: Whether there are messages you have not read. examples: - true unreadCount: type: integer description: How many messages you have not read. examples: - 1 isClosed: type: boolean description: Whether the conversation is closed. examples: - false isDraft: type: boolean description: Always `false` here. Drafts are not listed. examples: - false sendTyping: type: - boolean - 'null' description: >- Whether typing indicators are sent in this conversation. `null` follows the workspace setting. examples: - null lastMessage: type: - object - 'null' description: >- The most recent message. `null` when the conversation has no messages yet. required: - text - fromMe - seqId - createdAt - attachmentCount - attachmentType - seen properties: text: type: - string - 'null' description: The message text. `null` for a message with only an attachment. examples: - Thanks, sounds good. Send the details over. fromMe: type: - boolean - 'null' description: >- `true` when the connected account sent it, `false` when the other person did. examples: - false seqId: type: - string - 'null' description: The network's own reference for the message. examples: - '1900000000000000123' createdAt: type: - string - 'null' format: date-time description: When it was sent, in ISO 8601 UTC. examples: - '2026-10-17T14:05:00.000Z' attachmentCount: type: integer description: How many attachments it carries. examples: - 0 attachmentType: type: - string - 'null' description: >- The kind of attachment, such as `image`, `gif`, `video`, `audio` or `file`. `null` when there is none. examples: - null seen: type: - boolean - 'null' description: >- `true` when the other person has read your last message. `null` when that is not known, or when the last message came from them. examples: - null Platform: type: string enum: - x - linkedin description: The network the item belongs to. examples: - linkedin Participant: type: object description: >- The other person in a conversation. Profile details that are not known are `null`. LinkedIn profiles also carry `experience`, `education` and `skills`. additionalProperties: true required: - platform - platformId - userName - name - url - profilePicture - headline - canDm - isVerified - followers - following - location - description properties: platform: $ref: '#/components/schemas/Platform' platformId: type: - string - 'null' description: >- The ID the network gives this person. Always read together with `platform`. examples: - '1876543210987654321' userName: type: - string - 'null' description: >- The handle on X, or the public profile name on LinkedIn, without a prefix. examples: - janedoe name: type: - string - 'null' description: The display name. examples: - Jane Doe url: type: - string - 'null' description: Link to the profile on the network. examples: - https://x.com/janedoe profilePicture: type: - string - 'null' description: Link to the profile picture. examples: - https://example.com/avatars/janedoe.jpg headline: type: - string - 'null' description: The profile headline. LinkedIn only. examples: - Head of Growth at Northwind canDm: type: - boolean - 'null' description: >- Whether you can send this person a direct message. `null` when it is not known. examples: - true isVerified: type: boolean description: Whether the profile has a verification badge. examples: - false followers: type: - integer - 'null' description: Follower count, when the network shares it. examples: - 1280 following: type: - integer - 'null' description: Number of accounts the person follows, when the network shares it. examples: - 340 location: type: - string - 'null' description: The location on the profile. examples: - Berlin description: type: - string - 'null' description: The bio or about text. examples: - Growth, partnerships and outbound. isBlueVerified: type: boolean isVerifiedOrganization: type: boolean verified: type: - string - 'null' description: The verification badge. verifiedType: type: - string - 'null' createdAt: type: - string - 'null' description: When the profile was created on the network. coverPicture: type: - string - 'null' description: Link to the cover image. publicIdentifier: type: - string - 'null' description: The public profile name on LinkedIn. industry: type: - string - 'null' degree: type: - integer - 'null' description: Connection degree. LinkedIn only. isPremium: type: - boolean - 'null' isInfluencer: type: - boolean - 'null' isCreator: type: - boolean - 'null' type: type: string description: The kind of profile, such as a person or a company. experience: type: array items: type: object additionalProperties: true description: Jobs on the profile. LinkedIn only. education: type: array items: type: object additionalProperties: true description: Schools on the profile. LinkedIn only. skills: type: array items: type: string description: Skills on the profile. LinkedIn only. phones: type: array items: {} description: Phone numbers on the profile. websites: type: array items: {} description: Websites on the profile. honors: type: array items: {} description: Honors on the profile. birthday: type: - string - 'null' address: type: - string - 'null' connectedSince: type: - string - 'null' hasPublicKey: type: boolean isVerifiedOrganizationAffiliate: type: boolean Tag: type: object description: A label you can put on a conversation. required: - id - label - color properties: id: type: string description: The tag ID. examples: - 7c1f0c52-6d1a-4a49-9a63-2b3c4d5e6f70 label: type: string description: The tag name, up to 24 characters. examples: - Hot lead color: type: string description: The tag color as a lowercase six-digit hex value. examples: - '#e24c5d' Failure: type: object required: - status - data - error properties: status: type: boolean description: Always `false` for an error. data: type: 'null' description: Always `null` for an error. error: type: string description: What went wrong, in plain words. responses: Unauthorized: description: The API key is missing or not valid. content: application/json: schema: $ref: '#/components/schemas/Failure' example: status: false data: null error: Not authenticated PlanRequired: description: The workspace has no active plan, or its trial has ended. content: application/json: schema: $ref: '#/components/schemas/Failure' example: status: false data: null error: Your free trial has ended. Pick a plan to continue. ServerError: description: Something failed on our side. Try again. content: application/json: schema: $ref: '#/components/schemas/Failure' example: status: false data: null error: Something went wrong. Please try again. securitySchemes: bearerAuth: type: http scheme: Bearer description: >- Your API key, sent as `Authorization: Bearer YOUR_API_KEY`. Create one in **Settings → API**. x-default: Bearer YOUR_API_KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.