---
title: "List groups"
method: GET
path: "/groups"
tags: ["Groups"]
---

# List groups

`GET /groups`

## Request

- Base URL: `https://api.modem.dev/v1`
- URL: `https://api.modem.dev/v1/groups`
- Auth: HTTP bearer

List message groups (conversations) for a single company or person. Provide exactly one of companyId or personId.

## Query parameters

- `companyId` string
- `personId` string
- `page` integer
- `limit` integer

## Response `200`

OK

- object
  - `data` object[], required
    - `group` object, required
      - `archivedAt` string, date-time, nullable: Timestamp when the group was archived.
      - `endTimestamp` unknown
      - `id` string, uuid, required
      - `startTimestamp` unknown
    - `messages` object[], required
      - `content` string, required: Full text content of the message.
      - `createdAt` string, date-time: Timestamp when the message was created.
      - `deletedAt` string, date-time, nullable: Timestamp when the message was deleted, if applicable.
      - `editedAt` string, date-time, nullable: Timestamp when the message was last edited.
      - `id` union, required
        - string, uuid
        - string, uuid
      - `isInternal` boolean, required: Whether the message is an internal, team-only note withheld from the external/customer party (e.g. an internal agent note).
      - `metadata` object, nullable, required: Additional metadata captured for the message.
      - `replyToId` string, uuid, nullable, required: Internal message ID that this message replies to.
      - `sourceMessageId` string, required: Identifier of the message in the source system.
      - `sourceMessageType` string, required: Type/classification of the source message.
      - `sourceName` string, required: Source system the message was ingested from.
      - `sourceReplyToId` string, nullable, required: Source system ID of the message being replied to.
      - `sourceThreadId` string, nullable, required: Thread identifier in the source system.
      - `sourceUrl` string, uri, nullable, required: URL linking to the original message when available.
      - `threadId` string, uuid, nullable, required: Internal thread identifier when applicable.
      - `title` string, nullable, required: Optional title of the message.
      - `author` object, nullable, required
        - `displayName` string, nullable, required: Optional display name for the author.
        - `id` union, required
          - string, uuid
          - string, uuid
        - `isBot` boolean, required: Whether the author is a bot account.
        - `sourceAuthorId` string, required: Author identifier in the source system.
        - `sourceAvatarUrl` string, uri, nullable, required: Avatar image URL from the source system.
        - `sourceName` string, required: Source system where the author originates.
      - `channel` object, nullable, required
        - `channelName` string, required
        - `id` string, required
        - `serverName` string, required
      - `reactions` object[], required
        - `count` integer, required: Number of times this reaction was used.
        - `identifier` string, required: Normalized reaction identifier (e.g., "thumbsup", "heart").
        - `messageId` union, required: ID of the message this reaction belongs to.
          - string, uuid
          - string, uuid
        - `unicode` string, nullable, required: Unicode representation of the emoji if applicable.
      - `replyTo` object, nullable, required
        - `content` string, required: Full text content of the message.
        - `createdAt` string, date-time: Timestamp when the message was created.
        - `deletedAt` string, date-time, nullable: Timestamp when the message was deleted, if applicable.
        - `editedAt` string, date-time, nullable: Timestamp when the message was last edited.
        - `id` union, required
          - string, uuid
          - string, uuid
        - `isInternal` boolean, required: Whether the message is an internal, team-only note withheld from the external/customer party (e.g. an internal agent note).
        - `metadata` object, nullable, required: Additional metadata captured for the message.
        - `replyToId` string, uuid, nullable, required: Internal message ID that this message replies to.
        - `sourceMessageId` string, required: Identifier of the message in the source system.
        - `sourceMessageType` string, required: Type/classification of the source message.
        - `sourceName` string, required: Source system the message was ingested from.
        - `sourceReplyToId` string, nullable, required: Source system ID of the message being replied to.
        - `sourceThreadId` string, nullable, required: Thread identifier in the source system.
        - `sourceUrl` string, uri, nullable, required: URL linking to the original message when available.
        - `threadId` string, uuid, nullable, required: Internal thread identifier when applicable.
        - `title` string, nullable, required: Optional title of the message.
        - `author` object, nullable, required
          - `displayName` string, nullable, required: Optional display name for the author.
          - `id` union, required
            - string, uuid
            - string, uuid
          - `isBot` boolean, required: Whether the author is a bot account.
          - `sourceAuthorId` string, required: Author identifier in the source system.
          - `sourceAvatarUrl` string, uri, nullable, required: Avatar image URL from the source system.
          - `sourceName` string, required: Source system where the author originates.
      - `thread` object, nullable, required
        - `content` string, required: Full text content of the message.
        - `createdAt` string, date-time: Timestamp when the message was created.
        - `deletedAt` string, date-time, nullable: Timestamp when the message was deleted, if applicable.
        - `editedAt` string, date-time, nullable: Timestamp when the message was last edited.
        - `id` union, required
          - string, uuid
          - string, uuid
        - `isInternal` boolean, required: Whether the message is an internal, team-only note withheld from the external/customer party (e.g. an internal agent note).
        - `metadata` object, nullable, required: Additional metadata captured for the message.
        - `replyToId` string, uuid, nullable, required: Internal message ID that this message replies to.
        - `sourceMessageId` string, required: Identifier of the message in the source system.
        - `sourceMessageType` string, required: Type/classification of the source message.
        - `sourceName` string, required: Source system the message was ingested from.
        - `sourceReplyToId` string, nullable, required: Source system ID of the message being replied to.
        - `sourceThreadId` string, nullable, required: Thread identifier in the source system.
        - `sourceUrl` string, uri, nullable, required: URL linking to the original message when available.
        - `threadId` string, uuid, nullable, required: Internal thread identifier when applicable.
        - `title` string, nullable, required: Optional title of the message.
        - `author` object, nullable, required
          - `displayName` string, nullable, required: Optional display name for the author.
          - `id` union, required
            - string, uuid
            - string, uuid
          - `isBot` boolean, required: Whether the author is a bot account.
          - `sourceAuthorId` string, required: Author identifier in the source system.
          - `sourceAvatarUrl` string, uri, nullable, required: Avatar image URL from the source system.
          - `sourceName` string, required: Source system where the author originates.
    - `topic` object, nullable, required
      - `isV2` boolean, required
      - `keywords` string[], required
      - `linkedIssueKey` string, nullable, required
      - `sources` string[], required
      - `topicId` union, required
        - string, uuid
        - string, uuid
      - `topicTitle` string, required
      - `topicType` string, nullable, required
  - `limit` integer, required: The page size used for this response.
  - `page` integer, required: The 1-based page number returned.
  - `totalCount` integer, required: Total number of items matching the query, across all pages.

## Other responses

- `400`: Invalid request (validation failed).
- `401`: Missing or invalid API key.
- `403`: The API key does not have access to this resource.
- `404`: The requested resource was not found.
- `429`: Rate limit exceeded.
- `500`: Internal server error.

---

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