--- title: "Run Search Query" method: POST path: "/api/v2/search/query" tags: ["Search"] --- # Run Search Query `POST /api/v2/search/query` ## Request - Base URL: `https://console.jumpcloud.com` - URL: `https://console.jumpcloud.com/api/v2/search/query` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Query your JumpCloud data such as users, user groups, devices, and related objects using a structured JSON filter DSL. Use this endpoint to select fields, apply nested filters, sort and paginate results, and optionally aggregate data. **When to use** Building reports, dashboards, exports, or integrations that need filtered, join-aware queries over your JumpCloud data such as users, user groups, devices, and related objects. **When not to use** Free-text / keyword search across many fields at once. ## Headers - `x-org-id` string ## Request body - JumpcloudSearchSearchRequest - `aggregations` JumpcloudSearchSearchRequestAggregation[] - `field` string[]: This is a field on an object. It should always be in the form of . This will be case insensitive, and will be cast to lowercase always. - `function` 'function_unknown' | 'count' | 'avg' | 'max' | 'min' | 'sum' | 'count_unique' - `name` string - `cacheToken` string, nullable - `fields` JumpcloudSearchSearchRequestFields - `exclude` string[] - `include` string[] - `filters` JumpcloudSearchSearchRequestFilter[] - `field` string, nullable: This is a field on an object. It should always be in the form of . This will be case insensitive, and will be cast to lowercase always. - `filters` JumpcloudSearchSearchRequestFilter[]: Only allowed when operation is 'and'/'or'. This allows for logical groupings of sub-filters provided in this field's array. - `operation` 'operation_unknown' | 'and' | 'or' | 'equals' | 'not_equals' | 'greater_than' | 'less_than' | 'starts_with' | 'ends_with' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'greater_than_or_equals' | 'less_than_or_equals' | 'is_null' | 'is_empty' | 'equals_case_sensitive' | 'not_equals_case_sensitive' | 'starts_with_case_sensitive' | 'ends_with_case_sensitive' | 'contains_case_sensitive' | 'not_contains_case_sensitive' | 'in_case_sensitive' | 'not_in_case_sensitive' | 'member_of' | 'not_member_of' | 'not_contains_with_null' | 'not_contains_case_sensitive_with_null' | 'not_in_with_null' | 'not_in_case_sensitive_with_null' | 'not_starts_with' | 'not_ends_with': Filter operation to be applied: and - Provides logical 'and' groupings of all elements provided in the `filters` array (all sub-filter criteria must be satisfied). or - Provides logical 'or' groupings of all elements provided in the `filters` array (any sub-filter criteria can be satisfied). equals - Compares `field` with `value` for a // match. Case insensitive. not_equals - Compares `field` with `value` for an exact non-match. Case insensitive. greater_than - Checks if `field` is greater numerically than static `value` (non-inclusive). Works for numbers and datetime types. less_than - Checks if `field` is less than static `value` (non-inclusive). Works for numbers and datetime types. starts_with - Checks if `field` starts with static `value`. Case insensitive. Only works for string types. ends_with - Checks if `field` ends with static `value`. Case insensitive. Only works for string types. not_starts_with - Checks if `field` does not start with static `value`. Case insensitive. Only works for string types. not_ends_with - Checks if `field` does not end with static `value`. Case insensitive. Only works for string types. contains - Checks if `field` has the static `value` as its substring. Case insensitive. Only works for string types. not_contains - Checks if `field` does not have the static `value` as its substring. Case insensitive. Only works for string types. in - Checks if `field` is in the static `value` array. Works with strings (case insensitive), numbers, and datetime types. not_in - Checks if `field` is not in the static `value` array. Works with strings (case insensitive), numbers, and datetime types. greater_than_or_equals - Checks if `field` is greater than or equal to static `value`. Works for numbers and datetime types. less_than_or_equals - Checks if `field` is less than or equal to static `value`. Works for numbers and datetime types. is_null - Checks if `field` is null. Works for all field types. Requires boolean value (true for null, false for not null). is_empty - Checks if `field` is null or empty string. Works only for string field types. Requires boolean value (true for empty, false for not empty). equals_case_sensitive - Compares `field` with `value` for an exact match. Case sensitive. Only works for string types. not_equals_case_sensitive - Compares `field` with `value` for an exact non-match. Case sensitive. Only works for string types. starts_with_case_sensitive - Checks if `field` starts with static `value`. Case sensitive. Only works for string types. ends_with_case_sensitive - Checks if `field` ends with static `value`. Case sensitive. Only works for string types. contains_case_sensitive - Checks if `field` has the static `value` as its substring. Case sensitive. Only works for string types. not_contains_case_sensitive - Checks if `field` does not have the static `value` as its substring. Case sensitive. Only works for string types. in_case_sensitive - Checks if `field` is in the static `value` array. Works with strings (case sensitive), numbers, and datetime types. not_in_case_sensitive - Checks if `field` is not in the static `value` array. Works with strings (case sensitive), numbers, and datetime types. not_contains_with_null - Like not_contains but also matches rows where `field` IS NULL (v1 search API compatibility). not_contains_case_sensitive_with_null - Like not_contains_case_sensitive but also matches rows where `field` IS NULL (v1 search API compatibility). not_in_with_null - Like not_in but also matches rows where `field` IS NULL (v1 search API compatibility). not_in_case_sensitive_with_null - Like not_in_case_sensitive but also matches rows where `field` IS NULL (v1 search API compatibility). member_of - Array column overlaps with the given list. Only for array-typed fields. Value must be list_value. not_member_of - Array column does not overlap with the given list. Only for array-typed fields. Value must be list_value. - `query` JumpcloudSearchSearchRequest (recursive) - `unit` string, nullable - `value` unknown - `limit` integer: Maximum number of rows (inclusive) to return in the objects. Note that there is an implicit limit enforced always in the external API. - `metadata` JumpcloudSearchSearchRequestMetadata: Metadata about the search request including source information and some other metadata about the calling service. - `context` JumpcloudSearchMetadataContextEntry[] - `key` string - `value` string - `searchPurpose` 'unspecified' | 'reporting' | 'health_monitoring' | 'alerting' | 'audit' | 'troubleshooting' | 'user_initiated' | 'scheduled' | 'export' | 'analytics' | 'automation' | 'data_validation' - `source` string, nullable - `pagination` JumpcloudSearchPaginationParams: Parameters for controlling pagination of search results. - `offset` integer: Zero-based index of the first result to return. For example: 0 returns the first page, 100 returns the second page when page_size=100. - `pageSize` integer: Number of results to return per page. If not specified, uses server default (typically 50-100 items). - `requestCache` boolean - `sort` JumpcloudSearchSearchRequestSort[] - `field` string: This is a field on an object. It should always be in the form of . This will be case insensitive, and will be cast to lowercase always. - `order` 'asc' | 'desc' ## Response `200` A successful response. - JumpcloudSearchSearchResponse - `cacheToken` string, nullable - `metadata` JumpcloudSearchSearchMetadata - `queryTime` number, float - `schema` JumpcloudSearchSchemaField[] - `field` string - `format` string, nullable - `function` 'function_unknown' | 'count' | 'avg' | 'max' | 'min' | 'sum' | 'count_unique' - `type` 'type_unknown' | 'datetime' | 'boolean' | 'string' | 'number' | 'array': The type of the field. This is a enum that can be used as a hint to the underlying value's type. number: An integer or floating point number boolean: Either 'true' or 'false' datetime: An ISO 8601 date time. No offset will be provided, and can be assumed to be UTC. Ex. '2024-09-11T23:05:23Z' string: General text. array: A list of string values (e.g. PostgreSQL text[] or comma-separated string). - `results` JumpcloudSearchSearchResponseResult[] - `fields` JumpcloudSearchSearchResponseField[] - `field` string: This is a field on an object. It should always be in the form of . This will be case insensitive, and will be cast to lowercase always. - `function` 'function_unknown' | 'count' | 'avg' | 'max' | 'min' | 'sum' | 'count_unique' - `value` unknown - `itemnum` integer ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `500`: Internal Server Error --- [API](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api.md) - [All operations](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/revisions/f396d9271b46?raw)