# List tickets

Returns a list of tickets in your organization using cursor-based pagination.

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| limit | number | Number of tickets to return (1-100, default 10) |
| cursor | string | Cursor from previous response for pagination |
| ticketCategoryIds | string[] | Filter by ticket category IDs |
| statusIds | string[] | Filter by status IDs |
| q | string | Search query |
| assigneeId | string | Filter by assignee ID |
| categoryType | string | Filter by category type: "customer", "tracker", or "back-office" |
| sortBy | string | Sort field: "date" (default), "recent", or "ticketNumber" |
| sortOrder | string | Sort direction: "asc" or "desc" (default) |

### Response

Returns a list object with data (array of ticket objects) and nextCursor.

Endpoint: GET /v2/tickets
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Query parameters:

  - `limit` (integer)

  - `cursor` (string)

  - `ticketCategoryIds` (array)

  - `statusIds` (array)

  - `q` (string)

  - `assigneeId` (string)

  - `categoryType` (string)
    Enum: "customer", "tracker", "back-office"

  - `sortBy` (string)
    Enum: "date", "recent", "ticketNumber"

  - `sortOrder` (string)
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "list"

  - `data` (array, required)
    Array of tickets
    Example: []

  - `data.id` (string, required)
    Unique identifier (MongoDB ID)
    Example: "507f1f77bcf86cd799439011"

  - `data.ticketNumber` (number, required)
    Sequential display ID (e.g. TK-42)
    Example: 42

  - `data.title` (string, required)
    Ticket title
    Example: "Cannot login to dashboard"

  - `data.content` (string, required)
    Ticket content/description (HTML)
    Example: "<p>I get a 403 error when logging in.</p>"

  - `data.ticketCategoryId` (string, required)
    Ticket category ID
    Example: "507f1f77bcf86cd799439011"

  - `data.categoryType` (string, required)
    Ticket category type
    Enum: "customer", "tracker", "back-office"

  - `data.ticketUrl` (string, required)
    Full URL to view the ticket
    Example: "https://feedback.example.com/p/cannot-login"

  - `data.author` (object,null, required)
    Contact who created the ticket

  - `data.author.id` (string,null, required)
    Author unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `data.author.name` (string, required)
    Author display name
    Example: "John Doe"

  - `data.author.email` (string,null, required)
    Author email
    Example: "john@example.com"

  - `data.author.profilePicture` (string,null, required)
    Author profile picture URL
    Example: "https://cdn.example.com/avatars/john.png"

  - `data.author.type` (string, required)
    Type of user
    Enum: "admin", "customer", "guest", "integration", "bot", "lead"

  - `data.status` (object, required)
    Current ticket status

  - `data.status.id` (string, required)
    Unique identifier
    Example: "507f1f77bcf86cd799439011"

  - `data.status.name` (string, required)
    Display name
    Example: "In Progress"

  - `data.status.color` (string, required)
    Color for UI display
    Example: "Blue"

  - `data.status.type` (string, required)
    The workflow stage this status represents
    Enum: "reviewing", "unstarted", "active", "completed", "canceled"

  - `data.status.isDefault` (boolean, required)
    Whether this is the default status for new posts

  - `data.customFields` (object, required)
    Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects.
    Example: {"priority":"high","507f1f77bcf86cd799439099":"{\"key\":\"org/pending/file.pdf\",\"name\":\"document.pdf\",\"url\":\"https://...\"}"}

  - `data.companyId` (string,null, required)
    Associated company ID
    Example: "507f1f77bcf86cd799439015"

  - `data.assigneeId` (string,null, required)
    Assigned admin ID
    Example: "507f1f77bcf86cd799439013"

  - `data.teamAssigneeId` (string,null, required)
    Assigned team ID (from linked conversation)
    Example: "507f1f77bcf86cd799439014"

  - `data.open` (boolean, required)
    Whether the ticket is open
    Example: true

  - `data.snoozedUntil` (string,null, required)
    ISO 8601 timestamp until snoozed (from linked conversation)
    Example: "2025-01-16T09:00:00.000Z"

  - `data.linkedConversations` (array, required)
    Linked conversations

  - `data.linkedConversations.id` (string, required)
    Conversation ID
    Example: "507f1f77bcf86cd799439011"

  - `data.linkedConversations.role` (string, required)
    Link role
    Enum: "customer", "tracker", "back-office"

  - `data.conversationParts` (array)
    Conversation message history. Only included when fetching a single ticket by ID.

  - `data.createdAt` (string, required)
    ISO 8601 creation timestamp
    Example: "2025-01-15T10:30:00.000Z"

  - `data.updatedAt` (string, required)
    ISO 8601 last updated timestamp
    Example: "2025-01-15T12:30:00.000Z"

  - `data.integrations` (object, required)
    Third-party integration links

  - `data.integrations.linear` (array, required)

  - `data.integrations.linear.issueId` (string, required)
    Linear issue ID
    Example: "LIN-123"

  - `data.integrations.linear.issueUrl` (string,null, required)
    URL to the Linear issue
    Example: "https://linear.app/team/issue/LIN-123"

  - `data.integrations.jira` (array, required)

  - `data.integrations.jira.issueId` (string, required)
    Jira issue ID
    Example: "PROJ-456"

  - `data.integrations.jira.issueUrl` (string,null, required)
    URL to the Jira issue
    Example: "https://company.atlassian.net/browse/PROJ-456"

  - `data.integrations.clickup` (array, required)

  - `data.integrations.clickup.id` (string, required)
    ClickUp task ID
    Example: "86a1b2c3d"

  - `data.integrations.clickup.url` (string, required)
    URL to the ClickUp task
    Example: "https://app.clickup.com/t/86a1b2c3d"

  - `data.integrations.clickup.title` (string, required)
    ClickUp task title
    Example: "Fix login bug"

  - `data.integrations.github` (array, required)

  - `data.integrations.github.id` (string, required)
    GitHub issue ID
    Example: "1234567890"

  - `data.integrations.github.number` (string, required)
    GitHub issue number
    Example: "42"

  - `data.integrations.github.repositoryName` (string, required)
    Repository name
    Example: "frontend"

  - `data.integrations.github.repositoryFullName` (string, required)
    Full repository name (owner/repo)
    Example: "acme/frontend"

  - `data.integrations.github.url` (string, required)
    URL to the GitHub issue
    Example: "https://github.com/acme/frontend/issues/42"

  - `data.integrations.github.title` (string, required)
    GitHub issue title
    Example: "Login page returns 403"

  - `data.integrations.devops` (array, required)

  - `data.integrations.devops.id` (number, required)
    Azure DevOps work item ID
    Example: 789

  - `data.integrations.devops.url` (string, required)
    URL to the work item
    Example: "https://dev.azure.com/org/project/_workitems/edit/789"

  - `data.integrations.devops.projectId` (string, required)
    Azure DevOps project ID
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `data.integrations.devops.projectName` (string, required)
    Azure DevOps project name
    Example: "My Project"

  - `data.integrations.devops.title` (string, required)
    Work item title
    Example: "Implement SSO"

  - `data.integrations.hubspot` (array, required)

  - `data.integrations.hubspot.objectId` (number, required)
    HubSpot object ID
    Example: 12345

  - `data.integrations.hubspot.type` (string, required)
    HubSpot object type
    Enum: "TICKET", "DEAL", "CONTACT"

  - `data.integrations.hubspot.dealAmount` (number,null, required)
    Deal amount (for DEAL type)
    Example: 5000

  - `data.integrations.hubspot.dealClosed` (boolean,null, required)
    Whether the deal is closed (for DEAL type)

  - `nextCursor` (string,null, required)
    Cursor for fetching the next page
    Example: "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"

## Response 400 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "invalid_cursor"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 400