> ## Documentation Index > Fetch the complete documentation index at: https://talktohumans.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Use this endpoint to list and filter conversations from LinkedIn inbox or Sales Navigator. ## OpenAPI ````yaml /openapi.yaml get /v1/conversations openapi: 3.0.3 info: title: TalkToHumans Public API version: 1.0.0 license: name: Proprietary description: > Read and organize the LinkedIn workspace data your team already manages in TalkToHumans: accounts, people, tags, notes, sequence state, conversations, and views. servers: - url: https://api.talktohumans.app description: TalkToHumans API security: - bearerAuth: [] tags: - name: Organization description: Workspace details for the current API key. - name: LinkedIn description: >- Accounts, contacts, companies, and conversations already synced into TalkToHumans. - name: Enrich description: Profile enrichment for LinkedIn people and companies. - name: Views description: Saved TalkToHumans views and lists. paths: /v1/conversations: get: tags: - LinkedIn summary: List conversations description: > Use this endpoint to list and filter conversations from LinkedIn inbox or Sales Navigator. operationId: listConversations parameters: - name: tag in: query description: >- Filter by a participant tag. The connected account's own profile is ignored. schema: type: string - name: contact_id in: query description: >- Filter by TalkToHumans contact ID. Use a positive integer encoded as a string. schema: type: string pattern: ^[1-9][0-9]*$ - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: '200': description: Conversations matching the filters. content: application/json: schema: $ref: '#/components/schemas/ListConversationsEnvelope' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' components: parameters: Limit: name: limit in: query description: Page size. Defaults to 10. Values above 25 are clamped to 25. schema: type: integer minimum: 1 default: 10 maximum: 25 Cursor: name: cursor in: query description: Opaque cursor from the previous response's `pagination.next_cursor`. schema: type: string schemas: ListConversationsEnvelope: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/ListConversationsResponse' ListConversationsResponse: type: object additionalProperties: false required: - conversations - pagination properties: conversations: type: array items: $ref: '#/components/schemas/Conversation' pagination: $ref: '#/components/schemas/Pagination' Error: type: object additionalProperties: false required: - code - message properties: code: type: string description: Machine-readable error code. enum: - unauthorized - forbidden - not_found - bad_request - internal_error - conflict - rate_limit_exceeded - billing_payment_failed - billing_subscription_incomplete - billing_subscription_expired - billing_grace_period - billing_feature_not_available - billing_insufficient_credits - billing_invalid - upstream_error message: type: string description: Human-readable error message. debug: type: string description: Development-only debug details. Conversation: type: object additionalProperties: false required: - conversation_id - account - title - is_group - participants - app_url properties: conversation_id: type: string description: TalkToHumans conversation ID. account: $ref: '#/components/schemas/AccountSummary' title: type: string is_group: type: boolean participants: type: array items: $ref: '#/components/schemas/ConversationParticipant' last_message_text: type: string last_message_direction: type: string enum: - sent - received - '' last_message_at: type: string format: date-time nullable: true current_state: type: string sequence: $ref: '#/components/schemas/Sequence' app_url: type: string format: uri Pagination: type: object additionalProperties: false required: - limit - has_more properties: limit: type: integer format: int32 example: 10 has_more: type: boolean next_cursor: type: string description: Cursor for the next page. Omitted when there are no more results. AccountSummary: type: object additionalProperties: false required: - account_id - display_name - provider_account_id - owner_user_id properties: account_id: type: string description: TalkToHumans account ID. display_name: type: string provider_account_id: type: string description: LinkedIn provider account ID. owner_user_id: type: string description: TalkToHumans user ID that owns the account. ConversationParticipant: type: object additionalProperties: false required: - contact_id - provider_participant_id - name - relationship_status properties: account_relationship_id: type: string contact_id: type: string provider_participant_id: type: string public_identifier: type: string name: type: string first_name: type: string last_name: type: string headline: type: string primary_role_title: type: string primary_company_name: type: string linkedin_url: type: string format: uri avatar_url: type: string format: uri relationship_status: $ref: '#/components/schemas/RelationshipStatus' Sequence: type: object additionalProperties: false nullable: true required: - sequence_id - status - stop_if_person_replies - steps properties: sequence_id: type: string status: type: string stop_if_person_replies: type: boolean reply_guard_after: type: string format: date-time nullable: true next_step_id: type: string next_step_scheduled_for: type: string format: date-time nullable: true steps: type: array items: $ref: '#/components/schemas/SequenceStep' RelationshipStatus: type: string enum: - connected - not_connected - unknown SequenceStep: type: object additionalProperties: false required: - step_id - step_type - trigger_type - position - message_mode - state properties: step_id: type: string template_run_public_id: type: string step_type: type: string trigger_type: type: string position: type: integer format: int32 scheduled_for: type: string format: date-time nullable: true message_mode: type: string state: type: string responses: BadRequest: description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: bad_request message: Invalid request parameters Unauthorized: description: Missing, malformed, or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuthorization: value: code: unauthorized message: Authorization header is required invalidAuthorizationFormat: value: code: unauthorized message: Authorization header must use Bearer scheme invalidAPIKey: value: code: unauthorized message: Invalid API key Forbidden: description: >- API access is not enabled for the workspace, or the credential cannot access the requested workspace. content: application/json: schema: $ref: '#/components/schemas/Error' examples: forbidden: value: code: forbidden message: you don't have access to this organization featureUnavailable: value: code: billing_feature_not_available message: >- Feature 'TalkToHumansAPI' is not available in your current plan insufficientCredits: value: code: billing_insufficient_credits message: Insufficient credits RateLimited: description: >- Rate limit exceeded. Public routes allow 50 requests per 10 seconds per IP and endpoint. headers: Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: Rate limit exceeded InternalServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_error message: An internal error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: 'Pass your API key as `Authorization: Bearer `.' ````