> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Get Tickets > Returns the tickets of the workspace, newest first, excluding deleted tickets. ## OpenAPI ````yaml api-reference/openapi-generated.json GET /v1/tickets openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/tickets: get: tags: - Tickets summary: List tickets description: >- Returns the tickets of the workspace, newest first, excluding deleted tickets. operationId: listTickets parameters: - schema: type: integer nullable: true minimum: 0 description: >- Number of records to skip before the first returned record. Use together with limit to paginate: page N is offset = N * limit. Defaults to 0. example: 0 required: false description: >- Number of records to skip before the first returned record. Use together with limit to paginate: page N is offset = N * limit. Defaults to 0. name: offset in: query - schema: type: integer minimum: 1 maximum: 2000 description: >- Maximum number of tickets to return in one page (up to 2000). Defaults to 1000. example: 1000 required: false description: >- Maximum number of tickets to return in one page (up to 2000). Defaults to 1000. name: limit in: query - schema: type: string description: One or more raiser member emails (or "api"), comma-separated. example: user@example.com required: false description: One or more raiser member emails (or "api"), comma-separated. name: raised_by in: query - schema: type: string description: One or more assignee member emails, comma-separated. example: user@example.com required: false description: One or more assignee member emails, comma-separated. name: assignee in: query - schema: type: string description: One or more assigner member emails, comma-separated. example: user@example.com required: false description: One or more assigner member emails, comma-separated. name: assigned_by in: query - schema: type: string description: >- One or more statuses, comma-separated: 'open', 'inprogress', 'closed', 'archived'. example: open,inprogress required: false description: >- One or more statuses, comma-separated: 'open', 'inprogress', 'closed', 'archived'. name: status in: query - schema: type: string description: 'One or more priorities, comma-separated: 1 (low) to 4 (urgent).' example: 3,4 required: false description: 'One or more priorities, comma-separated: 1 (low) to 4 (urgent).' name: priority in: query - schema: type: integer minimum: 1 maximum: 4 description: Only tickets with priority at or above this value (1-4). example: 2 required: false description: Only tickets with priority at or above this value (1-4). name: priority_min in: query - schema: type: integer minimum: 1 maximum: 4 description: Only tickets with priority at or below this value (1-4). example: 4 required: false description: Only tickets with priority at or below this value (1-4). name: priority_max in: query - schema: type: string description: >- One or more labels, comma-separated — label names (matched exactly) or label_ids. Tickets carrying ANY of them match. example: urgent,billing required: false description: >- One or more labels, comma-separated — label names (matched exactly) or label_ids. Tickets carrying ANY of them match. name: label in: query - schema: type: string description: Only tickets created at or after this time (ISO 8601). example: '2026-01-01T00:00:00Z' required: false description: Only tickets created at or after this time (ISO 8601). name: start_time in: query - schema: type: string description: Only tickets created at or before this time (ISO 8601). example: '2026-01-31T23:59:00Z' required: false description: Only tickets created at or before this time (ISO 8601). name: end_time in: query - schema: type: string description: Only tickets due at or after this time (ISO 8601). example: '2026-01-01T00:00:00Z' required: false description: Only tickets due at or after this time (ISO 8601). name: due_date_start in: query - schema: type: string description: Only tickets due at or before this time (ISO 8601). example: '2026-01-31T23:59:00Z' required: false description: Only tickets due at or before this time (ISO 8601). name: due_date_end in: query - schema: type: string enum: - created_at - due_date - priority description: >- Field to sort by: 'created_at' (default), 'due_date' or 'priority'. example: priority required: false description: 'Field to sort by: ''created_at'' (default), ''due_date'' or ''priority''.' name: sort_by in: query - schema: type: string enum: - asc - desc description: 'Sort direction: ''asc'' or ''desc'' (default).' example: desc required: false description: 'Sort direction: ''asc'' or ''desc'' (default).' name: sort_order in: query - schema: type: string description: >- Case-insensitive substring search on the ticket subject and ticket_id. example: hello required: false description: >- Case-insensitive substring search on the ticket subject and ticket_id. name: q in: query responses: '200': description: Paginated list of tickets content: application/json: schema: type: object properties: from: type: integer description: >- 1-based index of the first record in this page (offset + 1). example: 1 to: type: integer description: 1-based index of the last record in this page. example: 20 count: type: integer description: >- Number of records in this page — the length of the `tickets` array, not the total across all pages. example: 20 tickets: type: array items: $ref: '#/components/schemas/Ticket' description: The tickets in this page. examples: default: summary: Response body value: from: 1 to: 20 count: 20 tickets: - ticket_id: ACM-001 org_id: 00000000-0000-0000-0000-000000000000 chat_id: 120363000000000000@g.us org_phone: 911111111111@c.us subject: Customer cannot access invoices status: open priority: 2 assignee: user@example.com assigned_by: user@example.com raised_by: api due_date: '2026-02-01T00:00:00+00:00' label_ids: label-aaaaaaaaaaaa: true labels: - urgent - billing custom_properties: Workspace: Example Corp quoted_message_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA created_at: '2026-01-15T09:30:00.000Z' last_updated_at: '2026-01-15T09:30:00.000Z' last_updated_by: user@example.com first_assigned_at: '2026-01-15T10:00:00.000Z' closed_at: null close_ticket_metadata: closed_by: user@example.com closed_at: '2026-01-20T17:45:00.000Z' closed_message: Resolved over call send_reply_message_id: null response_time: null is_deleted: false hubspot_metadata: {} freshdesk_metadata: {} zohodesk_metadata: {} '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', }); async function main() { const response = await client.tickets.listTickets(); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X GET 'https://api.periskope.app/v1/tickets' \ -H 'Authorization: Bearer YOUR_API_KEY' components: schemas: Ticket: type: object properties: ticket_id: type: string description: >- Unique human-readable id of the ticket, generated from the workspace ticket sequence (e.g. ACM-001). Use this value as the ticket_id path parameter. example: ACM-001 org_id: type: string format: uuid description: Id of the organization the ticket belongs to example: 00000000-0000-0000-0000-000000000000 chat_id: type: string description: >- Chat the ticket is raised on — @c.us for 1-1 chats, @g.us for group chats example: 120363000000000000@g.us org_phone: type: string description: >- Org phone (WhatsApp account) the chat belongs to, suffixed with @c.us. null for older tickets created before this column existed. example: 911111111111@c.us subject: type: string description: Subject of the ticket example: Customer cannot access invoices status: type: string enum: - open - inprogress - closed - archived description: >- Lifecycle status of the ticket: 'open', 'inprogress', 'closed' or 'archived' example: open priority: type: integer description: >- Priority of the ticket: 1 (low), 2 (medium), 3 (high) or 4 (urgent). 0 when no priority has been set. example: 2 assignee: type: string description: >- Email of the member the ticket is assigned to. null (or an empty string) when unassigned. example: user@example.com assigned_by: type: string description: >- Email of the member who assigned the ticket. null when the ticket has not been assigned. example: user@example.com raised_by: type: string description: >- Who raised the ticket: a member's email, or 'api' when created via the API example: api due_date: type: string description: >- Due date of the ticket as an ISO 8601 timestamp. null when no due date is set. example: '2026-02-01T00:00:00+00:00' label_ids: type: object additionalProperties: type: boolean description: >- Ids of the ticket labels applied to the ticket, as a map of label_id → true example: label-aaaaaaaaaaaa: true labels: type: array items: type: string description: >- Names of the ticket labels applied to the ticket, resolved from label_ids. Omitted when label_ids is null. example: - urgent - billing custom_properties: type: object additionalProperties: type: string description: >- Custom property values set on the ticket, as a map of property name → formatted display value (option ids are resolved to their labels). Only properties with a value are included. Property definitions are managed via the Properties endpoints (see the CustomProperty component). example: Workspace: Example Corp quoted_message_id: type: string description: >- Unique id of the message the ticket was raised from. null when the ticket is not linked to a message. example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA created_at: type: string description: When the ticket was created, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' last_updated_at: type: string description: When the ticket was last updated, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' last_updated_by: type: string description: >- Email of the member who last updated the ticket. null when the ticket has only been touched by the system or the API. example: user@example.com first_assigned_at: type: string description: >- When the ticket was first assigned to a member, as an ISO 8601 timestamp. null when it has never been assigned. example: '2026-01-15T10:00:00.000Z' closed_at: type: string description: >- When the ticket was closed, as an ISO 8601 timestamp. null while the ticket is not closed; cleared when a closed ticket is reopened. example: null close_ticket_metadata: $ref: '#/components/schemas/TicketCloseMetadata' response_time: type: number description: >- Seconds between the creation and closing of the ticket. Computed only for closed tickets — null otherwise. example: null is_deleted: type: boolean description: >- Whether the ticket has been deleted. Always false in list responses — deleted tickets are excluded there. example: false hubspot_metadata: type: object description: >- Sync metadata of the HubSpot integration. An empty object when the integration is not connected. example: {} freshdesk_metadata: type: object description: >- Sync metadata of the Freshdesk integration. An empty object when the integration is not connected. example: {} zohodesk_metadata: type: object description: >- Sync metadata of the Zoho Desk integration. An empty object when the integration is not connected. example: {} description: >- A ticket record — a tbl_chat_tickets row. Every ticket belongs to exactly one chat. Label ids are resolved into a labels array of names, and custom_properties maps ticket property names to their display values (property definitions are managed via the Properties endpoints). TicketCloseMetadata: type: object properties: closed_by: type: string description: >- Who closed the ticket: a member's email, or 'api' when closed via the API without a closed_by value example: user@example.com closed_at: type: string description: When the ticket was closed, as an ISO 8601 UTC timestamp example: '2026-01-20T17:45:00.000Z' closed_message: type: string description: >- Closing message supplied when the ticket was closed. null when none was given. example: Resolved over call send_reply_message_id: type: string description: >- Id of the WhatsApp reply sent on closing, when the dashboard close flow sent one. Always null for closes performed via the API. example: null description: >- Details recorded when the ticket was closed. An empty object for tickets that have never been closed; null after a closed ticket is reopened. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.