> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laburen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotation - List

> List annotations with filters. Optimized for list view with minimal includes for performance.

This endpoint retrieves a paginated list of annotations with optional filters. It supports:

* Filtering by agent, sentiment, conversation, message, or status
* Cursor-based pagination (20 items per page)
* Public agent access (no authentication required for public agents)
* Optimized response with minimal includes for performance

<Note>
  Authentication is **optional**. If no session is provided, you must include a `messageId` or `agentId` query parameter referencing a public agent to resolve the organization.
</Note>

### Query Parameters

<ParamField query="agentId" type="string">
  Filter annotations by agent ID (CUID format). Also used to resolve organization for public agents when no session is provided.
</ParamField>

<ParamField query="sentiment" type="string">
  Filter annotations by sentiment. Valid values: `good`, `bad` (case-insensitive).
</ParamField>

<ParamField query="conversationId" type="string">
  Filter annotations by conversation ID (CUID format).
</ParamField>

<ParamField query="messageId" type="string">
  Filter annotations by message ID (CUID format). Also used to resolve organization for public agents when no session is provided.
</ParamField>

<ParamField query="status" type="string">
  Filter annotations by status. Valid values depend on your organization's configuration.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination. Use the `id` of the last item from the previous page to fetch the next page.
</ParamField>

### Response

The response is an array of annotation objects (up to 20 items per page).

<ResponseField name="id" type="string">
  Unique identifier of the annotation (CUID format).
</ResponseField>

<ResponseField name="messageId" type="string">
  ID of the message this annotation refers to.
</ResponseField>

<ResponseField name="conversationId" type="string">
  ID of the conversation this annotation belongs to.
</ResponseField>

<ResponseField name="agentId" type="string">
  ID of the agent associated with this annotation.
</ResponseField>

<ResponseField name="organizationId" type="string">
  ID of the organization the annotation belongs to.
</ResponseField>

<ResponseField name="comment" type="string">
  Comment or feedback text for the annotation.
</ResponseField>

<ResponseField name="sentiment" type="string">
  Sentiment of the annotation (e.g., `good`, `bad`).
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the annotation.
</ResponseField>

<ResponseField name="createdById" type="string">
  ID of the user who created the annotation.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the annotation was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of when the annotation was last updated.
</ResponseField>

<ResponseField name="createdBy" type="object">
  Information about the user who created the annotation (minimal includes for performance).

  <Expandable title="CreatedBy object" defaultOpen>
    <ResponseField name="email" type="string">
      Email address of the user who created the annotation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tags" type="array">
  Tags associated with the annotation.

  <Expandable title="Tags array items">
    <ResponseField name="tag" type="object">
      Tag information.

      <Expandable title="Tag object">
        <ResponseField name="id" type="string">
          Tag ID.
        </ResponseField>

        <ResponseField name="name" type="string">
          Tag name.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  This endpoint returns minimal data for performance. For full annotation details including complete conversation context, use the [Get Annotation](/api-reference/endpoint/annotations/get) endpoint.
</Note>

### Error Responses

| Status Code | Type         | Description                                                                                         |
| ----------- | ------------ | --------------------------------------------------------------------------------------------------- |
| 401         | UNAUTHORIZED | No valid session and no public agent `agentId` or `messageId` provided, or the agent is not public. |

<RequestExample>
  ```bash cURL (authenticated) theme={null}
  curl --location --request GET 'https://dashboard.laburen.com/api/annotations?agentId=clxxxxxxxxxxxxxxxxx&status=pending' \
  --header 'Authorization: Bearer <API_KEY>'
  ```

  ```bash cURL (public agent) theme={null}
  curl --location --request GET 'https://dashboard.laburen.com/api/annotations?agentId=clxxxxxxxxxxxxxxxxx&sentiment=good'
  ```

  ```bash cURL (pagination) theme={null}
  curl --location --request GET 'https://dashboard.laburen.com/api/annotations?cursor=clxxxxxxxxxxxxxxxxx' \
  --header 'Authorization: Bearer <API_KEY>'
  ```

  ```javascript JavaScript theme={null}
  const apiUrl = 'https://dashboard.laburen.com/api';
  const apiKey = '<API_KEY>';

  // List annotations with filters
  const response = await fetch(`${apiUrl}/annotations?agentId=clxxxxxxxxxxxxxxxxx&status=pending`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
    },
  });

  const data = await response.json();
  console.log(data);

  // Pagination example
  const nextPage = await fetch(`${apiUrl}/annotations?cursor=${data[data.length - 1].id}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
    },
  });
  ```

  ```python Python theme={null}
  import requests

  api_url = "https://dashboard.laburen.com/api"
  api_key = "<API_KEY>"

  # List annotations with filters
  response = requests.get(
      f"{api_url}/annotations",
      params={
          "agentId": "clxxxxxxxxxxxxxxxxx",
          "status": "pending",
      },
      headers={
          "Authorization": f"Bearer {api_key}",
      },
  )

  data = response.json()
  print(data)

  # Pagination example
  if data:
      last_id = data[-1]["id"]
      next_page = requests.get(
          f"{api_url}/annotations",
          params={"cursor": last_id},
          headers={
              "Authorization": f"Bearer {api_key}",
          },
      )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "id": "clxxxxxxxxxxxxxxxxx",
      "messageId": "clxxxxxxxxxxxxxxxxx",
      "conversationId": "clxxxxxxxxxxxxxxxxx",
      "agentId": "clxxxxxxxxxxxxxxxxx",
      "organizationId": "clxxxxxxxxxxxxxxxxx",
      "comment": "The agent provided incorrect information about pricing",
      "sentiment": "bad",
      "status": "pending",
      "createdById": "clxxxxxxxxxxxxxxxxx",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "createdBy": {
        "email": "user@example.com"
      },
      "tags": [
        {
          "tag": {
            "id": "clxxxxxxxxxxxxxxxxx",
            "name": "bug"
          }
        }
      ]
    },
    {
      "id": "clxxxxxxxxxxxxxxxxx",
      "messageId": "clxxxxxxxxxxxxxxxxx",
      "conversationId": "clxxxxxxxxxxxxxxxxx",
      "agentId": "clxxxxxxxxxxxxxxxxx",
      "organizationId": "clxxxxxxxxxxxxxxxxx",
      "comment": "Great response, very helpful!",
      "sentiment": "good",
      "status": "completed",
      "createdById": "clxxxxxxxxxxxxxxxxx",
      "createdAt": "2024-01-15T09:15:00.000Z",
      "updatedAt": "2024-01-15T09:15:00.000Z",
      "createdBy": {
        "email": "user@example.com"
      },
      "tags": []
    }
  ]
  ```
</ResponseExample>