openapi: 3.1.0 info: version: '1.0' title: Zendesk Account Account Settings Search API description: Needs a description. tags: - name: Search paths: /api/v2/search: get: operationId: ListSearchResults tags: - Search summary: Zendesk Get Api V2 Search description: "Returns the search results. See [Query basics](#query-basics) for the syntax of the `query` parameter.\n\nUse the ampersand character (&) to append the `sort_by` or `sort_order` parameters to the URL.\n\nFor examples, see [Searching with Zendesk API](/documentation/ticketing/using-the-zendesk-api/searching-with-the-zendesk-api).\n\n#### Allowed For\n\n* Agents\n\n#### Pagination\n\n* Offset pagination only\n\nOffset pagination may result in duplicate results when paging. You can also use the\n[Export Search Results](/api-reference/ticketing/ticket-management/search/#export-search-results) endpoint, which\nuses cursor-based pagination and doesn't return duplicate results. See\n[Using cursor pagination](/api-reference/introduction/pagination/#using-cursor-pagination) for more information.\n\n\n#### Errors JSON Format\n\nErrors are represented as JSON objects which have the following keys:\n\n| Name | Type | Comment\n| --------------------- | ---------------------| --------------------\n| error | string | The type of error. Examples: \"unavailable\", \"invalid\"\n| description | string |\n\n##### Example Error\n```js\n{\n \"error\": \"unavailable\",\n \"description\": \"Sorry, we could not complete your search query. Please try again in a moment.\"\n}\n```\n" parameters: - name: query in: query description: The search query. See [Query basics](#query-basics) above. For details on the query syntax, see the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226) required: true schema: type: string example: https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed&sort_by=status&sort_order=desc - name: sort_by in: query description: One of `updated_at`, `created_at`, `priority`, `status`, or `ticket_type`. Defaults to sorting by relevance schema: type: string - name: sort_order in: query description: One of `asc` or `desc`. Defaults to `desc` schema: type: string responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' examples: default: $ref: '#/components/examples/SearchResponseExample' /api/v2/search/count: get: operationId: CountSearchResults tags: - Search summary: Zendesk Get Api V2 Search Count description: 'Returns the number of items matching the query rather than the items. The search string works the same as a regular search. #### Allowed For - Agents ' parameters: - name: query in: query description: The search query required: true schema: type: string example: https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/SearchCountResponse' examples: default: $ref: '#/components/examples/SearchCountResponseExample' /api/v2/search/export: get: operationId: ExportSearchResults tags: - Search summary: Zendesk Get Api V2 Search Export description: 'Exports a set of results. See [Query syntax](#query-syntax) for the syntax of the `query` parameter. Use this endpoint for search queries that will return more than 1000 results. The result set is ordered only by the `created_at` attribute. The search only returns results of a single object type. The following object types are supported: ticket, organization, user, or group. You must specify the type in the `filter[type]` parameter. Searches with type in the query string will result in an error. #### Allowed For - Agents #### Pagination - Cursor pagination See [Pagination](/api-reference/introduction/pagination/). Returns a maximum of 1000 records per page. The number of results shown in a page is determined by the `page[size]` parameter. **Note**: You may experience a speed reduction or a timeout if you request 1000 results per page and you have many archived tickets in the results. Try reducing the number of results per page. We recommend 100 results per page. The cursor specified by the `after_cursor` property in a response expires after one hour. For more information on cursor-based pagination, see the following articles: - [Comparing cursor pagination and offset pagination](/documentation/developer-tools/pagination/comparing-cursor-pagination-and-offset-pagination) - [Paginating through lists using cursor pagination](/documentation/developer-tools/pagination/paginating-through-lists-using-cursor-pagination) #### Limits This API endpoint is rate-limited to 100 requests per minute per account. The limit also counts towards the global API rate limit. #### Response Format | Name | Type | Comment | --------------------- | ---------------------| -------------------- | links[next] | string | URL to the next page of results | meta[has_more] | string | Boolean indicating if there are more results | meta[after_cursor] | string | Cursor object returned from the Search Service | results | array | May consist of tickets, users, groups, or organizations, as specified by the `filter_type` parameter The response is similar to the response of `GET /api/v2/search.json?`, with a few changes: * `links` - Has the following nested properties: `prev` and `next`. These replace the `next_page` and `prev_page` links. The `prev` property is always null because backward pagination is not supported. The `next` property may include an auto-generated link to the next page of results. * `meta` - Has the following nested properties: `has_more` and `after_cursor`. The `has_more` property indicates whether the next page has more results. The `after_cursor` property is the cursor used to paginate to the next page. It expires after one hour. There''s no `count` property. ' parameters: - name: query in: query description: The search query. See [Query basics](#query-basics) above. For details on the query syntax, see the [Zendesk Support search reference](https://support.zendesk.com/hc/en-us/articles/203663226) required: true schema: type: string example: https://subdomain.zendesk.com/api/v2/search.json?query=type:ticket status:closed&sort_by=status&sort_order=desc - name: page[size] in: query description: The number of results shown in a page. schema: type: integer - name: filter[type] in: query description: The object type returned by the export query. Can be `ticket`, `organization`, `user`, or `group`. schema: type: string responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/SearchExportResponse' examples: default: $ref: '#/components/examples/SearchExportResponseExample' components: schemas: SearchResponse: type: object properties: count: type: integer description: The number of resources returned by the query corresponding to this page of results in the paginated response readOnly: true facets: type: string description: The facets corresponding to the search query nullable: true readOnly: true next_page: type: string description: URL to the next page of results nullable: true readOnly: true previous_page: type: string description: URL to the previous page of results nullable: true readOnly: true results: type: array description: May consist of tickets, users, groups, or organizations, as specified by the `result_type` property in each result object items: $ref: '#/components/schemas/SearchResultObject' readOnly: true example: count: 1 facets: null next_page: null previous_page: null results: - created_at: '2018-04-06T03:17:05Z' default: false deleted: false description: '' id: 1835972 name: Ragtail result_type: group updated_at: '2018-04-06T03:17:05Z' url: https://example.zendesk.com/api/v2/groups/1835972.json SearchCountResponse: type: object properties: count: type: integer SearchExportResponse: type: object properties: facets: type: string description: The facets corresponding to the search query nullable: true readOnly: true links: type: object description: The links to the previous and next entries via the cursor ids in the metadata. properties: next: type: string description: The url to the next entry via the cursor. nullable: true readOnly: true prev: type: string description: The url to the previous entry via the cursor. nullable: true readOnly: true meta: type: object description: Metadata for the export query response. properties: after_cursor: type: string description: The cursor id for the next object. nullable: true readOnly: true before_cursor: type: string description: The cursor id for the previous object. nullable: true readOnly: true has_more: type: boolean description: Whether there are more items yet to be returned by the cursor. readOnly: true results: type: array description: May consist of tickets, users, groups, or organizations, as specified by the `result_type` property in each result object items: $ref: '#/components/schemas/SearchResultObject' readOnly: true example: facets: null links: next: https://example.zendesk.com/api/v2/search/export.json?filter%5Btype%5D=ticket&page%5Bafter%5D=eyJmaWVsZCI6ImNyZWF0ZWRfYXQiLCJkZXNjIjp0cnVlLCJ0aWVCcmVha0ZpZWxkIjoiaWQiLCJ0aWVCcmVha0Rlc2MiOmZhbHNlLCJzb3J0VmFsdWVzIjpudWxsLCJleHBvcnRlZFRodXNGYXIiOjAsInNlc3Npb25TdGFydCI6MTYwNzAzOTI1Mzk4NSwiY3JlYXRlZEF0IjoxNjA3MDM5MjUzOTg1LCJzYWx0ZWRSZXF1ZXN0SGFzaCI6LTQ5ODM0ODc3LCJzYWx0ZWRDdXJzb3JIYXNoIjotMjQwMzQ4MjgwfQ%3D%3D&page%5Bsize%5D=100&query=hello%26page%5Bsize%5D%3D100%26filter%5Btype%5D%3Dticket prev: null meta: after_cursor: eyJmaWVsZCI6ImNyZWF0ZWRfYXQiLCJkZXNjIjp0cnVlLCJ0aWVCcmVha0ZpZWxkIjoiaWQiLCJ0aWVCcmVha0Rlc2MiOmZhbHNlLCJzb3J0VmFsdWVzIjpudWxsLCJleHBvcnRlZFRodXNGYXIiOjAsInNlc3Npb25TdGFydCI6MTYwNzAzOTI1Mzk4NSwiY3JlYXRlZEF0IjoxNjA3MDM5MjUzOTg1LCJzYWx0ZWRSZXF1ZXN0SGFzaCI6LTQ5ODM0ODc3LCJzYWx0ZWRDdXJzb3JIYXNoIjotMjQwMzQ4MjgwfQ== before_cursor: null has_more: true results: []