> ## Documentation Index > Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt > Use this file to discover all available pages before exploring further. # List campaigns > Lists the tenant's campaigns with pagination, search and sorting. Unlike the legacy campaignList.js, `meta.totalCount`/`totalPages` are real aggregate counts — the frontend no longer needs to walk 5 pages of 200 to approximate a total (see acquireCampaignsStats in talqui-app-web). Returns HTTP 206 instead of 200 when more pages are available. ## OpenAPI ````yaml /api/services-api.yaml get /v1/tenants/{tenantID}/campaigns openapi: 3.0.3 info: description: >- Talqui is an omnichannel customer service platform that unifies conversations from WhatsApp, Instagram, Telegram, and many other channels into a single attendant panel, alongside a broader ecosystem of plugins and integrations. This API gives developers programmatic access to Talqui's services layer, exposing the operations needed to read and manage tenants, conversations, plugins, and related resources that power that platform. Authentication is available on behalf of an Operator (the default for this API), a Plugin Connection, or a Plugin — see the [Talqui authentication guide](https://docs.talqui.chat/guides/introduction/authentication/) for how each token is obtained and when to use it. Need help or have questions not covered here? Reach out to support@talqui.com. license: name: ISC url: https://opensource.org/license/isc-license-txt title: Talqui - Services API version: 0.65.0 servers: - description: Production url: https://services-api.talqui.chat security: [] tags: - name: Tenants - name: Settings - name: Analytics - name: Campaigns - name: Campaigns models - name: Contacts - name: Handoff links - name: Inboxes - name: Messages - name: Notifications - name: Sessions - name: Operators - name: Plugins - name: Setup - name: Uploads paths: /v1/tenants/{tenantID}/campaigns: get: tags: - Campaigns summary: List campaigns description: |- Lists the tenant's campaigns with pagination, search and sorting. Unlike the legacy campaignList.js, `meta.totalCount`/`totalPages` are real aggregate counts — the frontend no longer needs to walk 5 pages of 200 to approximate a total (see acquireCampaignsStats in talqui-app-web). Returns HTTP 206 instead of 200 when more pages are available. operationId: ListCampaignsController parameters: - in: path name: tenantID required: true schema: type: string - in: query name: page required: false schema: default: 1 description: 1-indexed page number to fetch. maximum: 9007199254740991 minimum: 1 type: integer - in: query name: perPage required: false schema: default: 50 description: Number of campaigns per page (max 200). maximum: 200 minimum: 1 type: integer - in: query name: sortBy required: false schema: default: createdAt description: Field to sort results by. enum: - createdAt - campaignID type: string - in: query name: sortDesc required: false schema: default: -1 description: 'Sort direction: -1 for descending, 1 for ascending.' maximum: 9007199254740991 minimum: -9007199254740991 type: integer - in: query name: search required: false schema: description: Free-text search against the campaign name. type: string - in: query name: filters required: false schema: description: JSON-encoded object of additional field filters. type: string responses: '200': content: application/json: schema: additionalProperties: false properties: data: description: Campaigns for the requested page. items: additionalProperties: false properties: campaignChannel: description: >- The channel this campaign dispatches through. Immutable once created. enum: - urn:talqui:whatsapp-gup:0 - urn:talqui:whatsapp-zapi:0 - urn:talqui:whatsapp-cloud:0 type: string campaignContactAttributes: description: >- Display metadata for the audience selection made for this campaign. items: {} type: array campaignContactIDs: description: Recipient contact ids for this campaign. items: type: string type: array campaignContactTags: description: >- Slugified tags applied to every contact this campaign reaches. items: type: string type: array campaignID: description: Unique identifier for this campaign. type: string campaignInboxID: description: >- Custom inbox a conversation opened by this campaign is assigned to. Null means none. nullable: true type: string campaignMeta: additionalProperties: {} description: Arbitrary metadata attached to the campaign. type: object campaignMetrics: additionalProperties: false description: >- Dispatch progress metrics, present on list responses. properties: pending: description: Dispatches still pending or processing. type: number sended: description: >- Dispatches that finished processing (success, failure or canceled). type: number total: description: >- Total dispatches created for this campaign so far. type: number required: - total - pending - sended type: object campaignModelID: description: The approved template this campaign uses. nullable: true type: string campaignName: description: Operator-facing name of the campaign. type: string campaignPluginConnectionID: description: >- Which specific PluginConnection (e.g. WhatsApp number) sends this campaign. Null on legacy campaigns. nullable: true type: string campaignSessionTags: description: >- Slugified tags applied to every conversation this campaign opens. items: type: string type: array campaignSessionType: description: >- How a conversation opened by this campaign continues. Null means the dispatch engine decides. enum: - auto - queued nullable: true type: string campaignStatus: description: Current lifecycle status of the campaign. enum: - draft - scheduled - processing - success - failure - canceled type: string campaignTag: description: Free-text tag for organizing campaigns. nullable: true type: string campaignVariables: description: >- Legacy global (non-per-contact) template variable values. canceledAt: description: When this campaign was canceled, if it was. format: date-time nullable: true type: string createdAt: description: When this campaign was created. format: date-time type: string createdBy: description: operatorID of whoever created this campaign. type: string dispatchAt: description: >- When this campaign is scheduled to start dispatching. format: date-time nullable: true type: string organizationID: description: The Talqui organization this campaign belongs to. type: string tenantID: description: The tenant this campaign belongs to. type: string updatedAt: description: When this campaign was last updated. format: date-time type: string updatedBy: description: operatorID of whoever last updated this campaign. type: string required: - organizationID - tenantID - campaignID - campaignName - campaignStatus - campaignChannel - campaignPluginConnectionID - campaignModelID - campaignContactIDs - campaignContactAttributes - campaignVariables - campaignTag - campaignSessionTags - campaignContactTags - campaignSessionType - campaignInboxID - campaignMeta - dispatchAt - canceledAt - createdBy - createdAt - updatedBy - updatedAt type: object type: array meta: additionalProperties: false description: Pagination metadata. properties: count: description: Number of items in this page. type: number currentPage: description: The page number returned. type: number hasMore: description: Whether more pages are available. type: boolean perPage: description: Number of items per page. type: number totalCount: description: Total number of campaigns matching the query. type: number totalPages: description: Total number of pages available. type: number required: - hasMore - count - totalCount - totalPages - currentPage - perPage type: object required: - data - meta type: object description: Response for status 200. '206': content: application/json: schema: additionalProperties: false properties: data: description: Campaigns for the requested page. items: additionalProperties: false properties: campaignChannel: description: >- The channel this campaign dispatches through. Immutable once created. enum: - urn:talqui:whatsapp-gup:0 - urn:talqui:whatsapp-zapi:0 - urn:talqui:whatsapp-cloud:0 type: string campaignContactAttributes: description: >- Display metadata for the audience selection made for this campaign. items: {} type: array campaignContactIDs: description: Recipient contact ids for this campaign. items: type: string type: array campaignContactTags: description: >- Slugified tags applied to every contact this campaign reaches. items: type: string type: array campaignID: description: Unique identifier for this campaign. type: string campaignInboxID: description: >- Custom inbox a conversation opened by this campaign is assigned to. Null means none. nullable: true type: string campaignMeta: additionalProperties: {} description: Arbitrary metadata attached to the campaign. type: object campaignMetrics: additionalProperties: false description: >- Dispatch progress metrics, present on list responses. properties: pending: description: Dispatches still pending or processing. type: number sended: description: >- Dispatches that finished processing (success, failure or canceled). type: number total: description: >- Total dispatches created for this campaign so far. type: number required: - total - pending - sended type: object campaignModelID: description: The approved template this campaign uses. nullable: true type: string campaignName: description: Operator-facing name of the campaign. type: string campaignPluginConnectionID: description: >- Which specific PluginConnection (e.g. WhatsApp number) sends this campaign. Null on legacy campaigns. nullable: true type: string campaignSessionTags: description: >- Slugified tags applied to every conversation this campaign opens. items: type: string type: array campaignSessionType: description: >- How a conversation opened by this campaign continues. Null means the dispatch engine decides. enum: - auto - queued nullable: true type: string campaignStatus: description: Current lifecycle status of the campaign. enum: - draft - scheduled - processing - success - failure - canceled type: string campaignTag: description: Free-text tag for organizing campaigns. nullable: true type: string campaignVariables: description: >- Legacy global (non-per-contact) template variable values. canceledAt: description: When this campaign was canceled, if it was. format: date-time nullable: true type: string createdAt: description: When this campaign was created. format: date-time type: string createdBy: description: operatorID of whoever created this campaign. type: string dispatchAt: description: >- When this campaign is scheduled to start dispatching. format: date-time nullable: true type: string organizationID: description: The Talqui organization this campaign belongs to. type: string tenantID: description: The tenant this campaign belongs to. type: string updatedAt: description: When this campaign was last updated. format: date-time type: string updatedBy: description: operatorID of whoever last updated this campaign. type: string required: - organizationID - tenantID - campaignID - campaignName - campaignStatus - campaignChannel - campaignPluginConnectionID - campaignModelID - campaignContactIDs - campaignContactAttributes - campaignVariables - campaignTag - campaignSessionTags - campaignContactTags - campaignSessionType - campaignInboxID - campaignMeta - dispatchAt - canceledAt - createdBy - createdAt - updatedBy - updatedAt type: object type: array meta: additionalProperties: false description: Pagination metadata. properties: count: description: Number of items in this page. type: number currentPage: description: The page number returned. type: number hasMore: description: Whether more pages are available. type: boolean perPage: description: Number of items per page. type: number totalCount: description: Total number of campaigns matching the query. type: number totalPages: description: Total number of pages available. type: number required: - hasMore - count - totalCount - totalPages - currentPage - perPage type: object required: - data - meta type: object description: Response for status 206. '400': content: application/json: schema: properties: errors: items: oneOf: - $ref: '#/components/schemas/MissingTenantIDError' - $ref: '#/components/schemas/RequestValidationError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MissingTenantIDError (error_code 1001): tenantID absent from the URL. | RequestValidationError (error_code 1002): query params fail schema validation. '401': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/UnauthorizedError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: 'UnauthorizedError (error_code 1003): missing/invalid operator token.' '403': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/ForbiddenError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: 'ForbiddenError (error_code 1004): operator token rejected upstream.' '500': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/UnknownError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- UnknownError (error_code 5999): Unexpected internal error not otherwise documented for this endpoint. security: - operatorAuth: [] components: schemas: MissingTenantIDError: additionalProperties: false properties: error: enum: - MissingTenantIDError type: string error_code: enum: - 1001 type: number message: example: tenantID is required. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object RequestValidationError: additionalProperties: false properties: error: enum: - RequestValidationError type: string error_code: enum: - 1002 type: number fields: items: additionalProperties: false properties: allowed: type: string field: type: string received: type: string required: - field - received - allowed type: object type: array message: example: Invalid request data. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message - fields type: object UnauthorizedError: additionalProperties: false properties: error: enum: - UnauthorizedError type: string error_code: enum: - 1003 type: number message: example: You are not authorized to perform this request. type: string statusCode: enum: - 401 type: number required: - statusCode - error - error_code - message type: object ForbiddenError: additionalProperties: false properties: error: enum: - ForbiddenError type: string error_code: enum: - 1004 type: number message: example: You do not have access to this resource. type: string statusCode: enum: - 403 type: number required: - statusCode - error - error_code - message type: object UnknownError: additionalProperties: false properties: error: enum: - UnknownError type: string error_code: enum: - 5999 type: number message: example: For some unknown reason your request has not succeeded. type: string statusCode: enum: - 500 type: number required: - statusCode - error - error_code - message type: object securitySchemes: operatorAuth: bearerFormat: JWT description: >- Behalf of an Operator (default). A JWT issued by Talqui Core when an operator signs in, scoped to every tenant that operator belongs to. Send as `Authorization: Bearer `. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.