---
title: "List threads"
method: GET
path: "/threads"
tags: ["Threads"]
---

# List threads

`GET /threads`

## Request

- Base URL: `https://inboxapp.com/api/v2`
- URL: `https://inboxapp.com/api/v2/threads`
- Auth: HTTP bearer

Threads in inbox order, filtered by folder and by contact CRM state.

## Query parameters

- `accountLinkId` Cuid2[]: Threads of these account links. Repeat the key to match any of several.
- `platform` Platform[]: Repeat the key to match any of several.
- `contactId` Cuid2[]: Threads with these contacts. With `accountLinkId`, finds the thread between an account and a contact. Repeat the key to match any of several.
- `folder` 'inbox' | 'noReply' | 'requests' | 'archived' | 'all': Defaults to `inbox`, threads that are neither archived nor requests. `noReply` is the `inbox` threads whose latest activity is inbound. `requests` holds unarchived threads where `isRequest` is true. `archived` includes requests. `all` spans every folder. Every other filter narrows the folder.
- `tag` string[]: Threads whose contact has one of these tags. Repeat the key to match any of several.
- `status` string[]: Threads whose contact has one of these statuses. Repeat the key to match any of several.
- `assigneeId` Cuid2[]: Threads whose `assigneeId`, the thread's own assignee or else its contact's, is one of these members. Repeat the key to match any of several.
- `unassigned` boolean: `true` keeps threads with no assignee, including through their contact. Not combinable with `assigneeId`.
- `campaignId` Cuid2[]: Threads these campaigns sent a message in. Campaign sends archive the thread, so pair it with `folder=archived` or `all`. Repeat the key to match any of several.
- `q` string: Searches profile display names, usernames and the activity preview. Results follow `order`, not relevance.
- `order` 'desc' | 'asc': Sort direction by inbox order: `activity.at`, or `createdAt` for a thread with no activity. A reminder or an accepted message request moves a thread up until its next message, without changing `activity.at`. Defaults to `desc`, newest first.
- `expand` string[]: Related resources to embed next to their ID field, one path per key, at most 4.
- `limit` integer: Page size, from 1 to 100. Defaults to 50.
- `cursor` string: The previous page's `nextCursor`. Opaque, and valid only with the filters it was issued for.

## Response `200`

OK

- ThreadPage: In inbox order, newest first unless `order` is `asc`.
  - `data` Thread[], required
    - `id` string, required
    - `platform` string, required: Always the platform of the thread's account link and profile.
    - `platformId` string, nullable, required: The ID the platform gives this object. Only meaningful next to its `platform`.
    - `accountLinkId` string, required: An account link: a platform account the team connected to Inboxapp, the team's side of a conversation.
    - `profileId` string, required: A profile: one person's account on one platform. Not a contact ID.
    - `contactId` string, required: A contact: the team's record of the person, with their status, tags, notes, valuation and default assignee.
    - `assigneeId` string, nullable, required: A member: a person on the team.
    - `isRequest` boolean, required: True while the conversation is an incoming request the account hasn't replied to or accepted. Requests are in the `requests` folder, not `inbox`.
    - `acceptanceState` 'required' | 'notRequired' | 'unknown', required: Whether the platform needs the account to accept the conversation before replying normally. `unknown` when the platform doesn't say. Independent of `isRequest`.
    - `archived` boolean, required
    - `unread` boolean, required: Marked unread in Inboxapp for the team owner, whose view the API takes. A thread no one has opened yet is not unread.
    - `restrictions` string[], required: Capabilities the platform disables in this conversation, on top of the account link's `capabilities`. Using one fails with `threadRestricted`.
    - `syncing` boolean, required: True while Inboxapp imports the conversation's older messages, so the message list may be incomplete.
    - `typingIndicators` 'enabled' | 'disabled' | 'teamDefault', required: Whether Inboxapp sends typing indicators to the platform while someone composes in this thread. `teamDefault` follows the team's setting.
    - `lastMessage` LastMessage, required: The thread's latest message. Get it for its content.
      - `id` string, required
      - `direction` 'inbound' | 'outbound', required: `inbound` was received from the other side. `outbound` was sent by the account link.
      - `createdAt` string, date-time, required
    - `activity` ThreadActivity, required: The thread's latest activity: a message, or a reaction since. `at` is when it happened, which is not always the thread's position in a list: see `order`.
      - `preview` string, nullable, required: One line as the inbox shows it, such as the message text or `You reacted with 👍`. Null when there is nothing to show.
      - `direction` 'inbound' | 'outbound', required: `outbound` when the account link acted.
      - `at` string, date-time, required
    - `createdAt` string, date-time, required
    - `accountLink` AccountLink: A platform account the team connected to Inboxapp. Every conversation and message goes through one.
      - `id` string, required
      - `platform` string, required: The platform. Every team can use twitter, linkedin; a team may have others enabled.
      - `platformId` string, required: The ID the platform gives this object. Only meaningful next to its `platform`.
      - `username` string, nullable, required: The platform username, without a display prefix such as `@`.
      - `displayName` string, nullable, required
      - `avatarUrl` string, nullable, required
      - `status` 'active' | 'offline' | 'paused', required: `active` sends and syncs. `paused` is stopped for the reasons in `pauseReasons`, and resumes once none remain. `offline` lost its connection to the platform and must be reconnected in Inboxapp.
      - `pauseReasons` string[], required: Why the account link is paused. New reasons may be added.
      - `capabilities` string[], required: What this account can do: its platform's capabilities, narrowed for this account. An operation it lacks fails with `capabilityNotSupported`.
      - `syncedAt` string, date-time, nullable, required: When Inboxapp finished importing the account's conversations. Null until then.
      - `createdAt` string, date-time, required
    - `profile` Profile: One person's account on one platform. Profile data is shared across teams; the team's own data about the person is on their contact.
      - `id` string, required
      - `platform` string, required: The platform. Every team can use twitter, linkedin; a team may have others enabled.
      - `platformId` string, required: The ID the platform gives this object. Only meaningful next to its `platform`.
      - `username` string, required: The platform username, without a display prefix such as `@`.
      - `handle` string, required: The username as the platform displays it. Show this, and look up by `username`.
      - `displayName` string, required
      - `avatarUrl` string, nullable, required
      - `bio` string, nullable, required
      - `location` string, nullable, required
      - `websiteUrl` string, nullable, required
      - `websiteDomain` string, nullable, required
      - `verified` boolean, required: The platform vouches for the account, such as with an X badge. Platform-specific badges are in `platformData`.
      - `isOrganization` boolean, required: A company or page rather than a person.
      - `isProtected` boolean, required: The account's posts are visible only to approved followers.
      - `followerCount` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `followingCount` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `postCount` union, required
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `engagementCount` union, required: On X, how many posts the user has liked.
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `listedCount` union, required: On X, how many lists include the profile.
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `accountStatus` 'active' | 'suspended' | 'notFound', required: `suspended` by the platform, or `notFound` when deleted or deactivated.
      - `platformCreatedAt` string, date-time, nullable, required: When the account was created on the platform.
      - `profileUrl` string, nullable, required
      - `updatedAt` string, date-time, required: When Inboxapp last stored a change to this profile.
      - `platformData` union, required: Fields only one platform has, tagged by `_tag`. Ignore tags you don't know.
        - object
          - `_tag` 'twitter', required
          - `badge` 'blue' | 'gold' | 'gray', nullable, required
          - `profileType` 'personal' | 'business' | 'government', required
          - `professionalCategory` string, nullable, required
          - `urlEntities` object[], required
            - `url` string, required
            - `expandedUrl` string, required
            - `displayUrl` string, required
            - `indices` unknown[], required
              - …
          - `bannerUrl` string, nullable, required
          - `rawData` object, nullable, required
        - object
          - `_tag` 'linkedin', required
          - `profileUrn` string, nullable
          - `kind` 'member' | 'organization', nullable
          - `memberBadge` 'premium' | 'verified', nullable
          - `bannerUrl` string, nullable
          - `bannerSize` object, nullable
            - `width` number, required
            - `height` number, required
          - `hydratedAt` string, nullable
          - `imageAssetId` string, nullable
          - `connectionsCount` number, nullable
          - `currentRole` string, nullable
          - `currentRoleStart` object, nullable
            - `year` number, required
            - `month` number, nullable, required
          - `currentCompanyName` string, nullable
          - `currentCompanyUrn` string, nullable
          - `topSchoolName` string, nullable
          - `topSchoolUrn` string, nullable
          - `topSchoolDegree` string, nullable
          - `topSchoolPeriod` string, nullable
          - `employeeCount` number, nullable
          - `employeeCountRange` object, nullable
            - `start` number, required
            - `end` number, nullable, required
          - `industry` string, nullable
          - `pageKind` 'company' | 'school' | 'showcase', nullable
          - `currentCompanyLogoUrl` string, nullable
          - `topSchoolLogoUrl` string, nullable
        - object: A platform the team has enabled beyond those every team can use. Its fields are not listed here.
          - `_tag` string, required
      - `relationships` Relationship[], required: One entry per team account link that has interacted with the profile.
        - `accountLinkId` string, required
        - `degree` 'self' | 'first' | 'second' | 'third' | 'outOfNetwork', nullable, required: How close the profile is to the account link on the platform's network, as last observed. `null` when never observed.
        - `connectionRequest` object, nullable, required: The account link's pending connection request. `null` once the profile is seen accepting it or the request is withdrawn, or when none was sent.
          - `sentAt` string, date-time, required
    - `contact` Contact: The team's record of a person: their profiles, plus the team's CRM state about them.
      - `id` string, required
      - `profiles` Profile[], required: The person's profiles, oldest link first. Profiles on platforms unavailable to the team are left out.
        - `id` string, required
        - `platform` string, required: The platform. Every team can use twitter, linkedin; a team may have others enabled.
        - `platformId` string, required: The ID the platform gives this object. Only meaningful next to its `platform`.
        - `username` string, required: The platform username, without a display prefix such as `@`.
        - `handle` string, required: The username as the platform displays it. Show this, and look up by `username`.
        - `displayName` string, required
        - `avatarUrl` string, nullable, required
        - `bio` string, nullable, required
        - `location` string, nullable, required
        - `websiteUrl` string, nullable, required
        - `websiteDomain` string, nullable, required
        - `verified` boolean, required: The platform vouches for the account, such as with an X badge. Platform-specific badges are in `platformData`.
        - `isOrganization` boolean, required: A company or page rather than a person.
        - `isProtected` boolean, required: The account's posts are visible only to approved followers.
        - `followerCount` union, required
          - number
          - 'Infinity' | '-Infinity' | 'NaN'
        - `followingCount` union, required
          - number
          - 'Infinity' | '-Infinity' | 'NaN'
        - `postCount` union, required
          - number
          - 'Infinity' | '-Infinity' | 'NaN'
        - `engagementCount` union, required: On X, how many posts the user has liked.
          - number
          - 'Infinity' | '-Infinity' | 'NaN'
        - `listedCount` union, required: On X, how many lists include the profile.
          - number
          - 'Infinity' | '-Infinity' | 'NaN'
        - `accountStatus` 'active' | 'suspended' | 'notFound', required: `suspended` by the platform, or `notFound` when deleted or deactivated.
        - `platformCreatedAt` string, date-time, nullable, required: When the account was created on the platform.
        - `profileUrl` string, nullable, required
        - `updatedAt` string, date-time, required: When Inboxapp last stored a change to this profile.
        - `platformData` union, required: Fields only one platform has, tagged by `_tag`. Ignore tags you don't know.
          - object
            - `_tag` 'twitter', required
            - `badge` 'blue' | 'gold' | 'gray', nullable, required
            - `profileType` 'personal' | 'business' | 'government', required
            - `professionalCategory` string, nullable, required
            - `urlEntities` object[], required
              - …
            - `bannerUrl` string, nullable, required
            - `rawData` object, nullable, required
          - object
            - `_tag` 'linkedin', required
            - `profileUrn` string, nullable
            - `kind` 'member' | 'organization', nullable
            - `memberBadge` 'premium' | 'verified', nullable
            - `bannerUrl` string, nullable
            - `bannerSize` object, nullable
              - …
            - `hydratedAt` string, nullable
            - `imageAssetId` string, nullable
            - `connectionsCount` number, nullable
            - `currentRole` string, nullable
            - `currentRoleStart` object, nullable
              - …
            - `currentCompanyName` string, nullable
            - `currentCompanyUrn` string, nullable
            - `topSchoolName` string, nullable
            - `topSchoolUrn` string, nullable
            - `topSchoolDegree` string, nullable
            - `topSchoolPeriod` string, nullable
            - `employeeCount` number, nullable
            - `employeeCountRange` object, nullable
              - …
            - `industry` string, nullable
            - `pageKind` 'company' | 'school' | 'showcase', nullable
            - `currentCompanyLogoUrl` string, nullable
            - `topSchoolLogoUrl` string, nullable
          - object: A platform the team has enabled beyond those every team can use. Its fields are not listed here.
            - `_tag` string, required
        - `relationships` Relationship[], required: One entry per team account link that has interacted with the profile.
          - `accountLinkId` string, required
          - `degree` 'self' | 'first' | 'second' | 'third' | 'outOfNetwork', nullable, required: How close the profile is to the account link on the platform's network, as last observed. `null` when never observed.
          - `connectionRequest` object, nullable, required: The account link's pending connection request. `null` once the profile is seen accepting it or the request is withdrawn, or when none was sent.
            - `sentAt` string, date-time, required
      - `statusId` string, nullable, required: A status: a pipeline stage on the team's board.
      - `tagIds` string[], required
      - `notes` string, nullable, required
      - `valuation` union, required: What the person is worth to the team, in the team's `currency`.
        - number
        - 'Infinity' | '-Infinity' | 'NaN'
      - `assigneeId` string, nullable, required: A member: a person on the team.
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
      - `status` Status: A pipeline stage on the team's board. A contact has at most one status.
        - `id` string, required
        - `name` string, required: Unique within the team, ignoring case and accents.
        - `color` string, nullable, required: A lowercase hex color.
        - `createdAt` string, date-time, required
      - `tags` Tag[]
        - `id` string, required
        - `name` string, required: Unique within the team, ignoring case and accents.
        - `color` string, required: A lowercase hex color.
      - `assignee` Member: A person on the team, who can be assigned threads and contacts.
        - `id` string, required: The member ID that `assigneeId` fields take.
        - `name` string, nullable, required
        - `email` string, required
        - `imageUrl` string, nullable, required
        - `role` 'owner' | 'admin' | 'user', required: `owner` and `admin` manage the team. A `user` can't change settings, billing or members.
        - `createdAt` string, date-time, required
    - `assignee` Member: A person on the team, who can be assigned threads and contacts.
      - `id` string, required: The member ID that `assigneeId` fields take.
      - `name` string, nullable, required
      - `email` string, required
      - `imageUrl` string, nullable, required
      - `role` 'owner' | 'admin' | 'user', required: `owner` and `admin` manage the team. A `user` can't change settings, billing or members.
      - `createdAt` string, date-time, required
  - `nextCursor` string, nullable, required: Pass it back as `cursor`, with the same filters, to read the next page. Null on the last page.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/inboxapp/apis/inboxapp-api.md) · [All operations](https://skmtc.dev/inboxapp/apis/inboxapp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inboxapp/apis/inboxapp-api/revisions/7f9bbf45e851?raw)