> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/6/api-reference/guides/ops-manager-search-api/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Operations Manager search APIs > Advanced query parameters, search operators, projection, sorting, and pagination for the Operations Manager jobs and tasks search APIs. Operations Manager includes two search APIs that support advanced functionality through query parameters. | Search API | | ------------------------------- | | `GET /operations-manager/jobs` | | `GET /operations-manager/tasks` | The information on this page applies only to the `/jobs` and `/tasks` APIs. ## Query parameter syntax Operations Manager uses an object syntax to express operators and their relationship to the fields they operate on. To get all documents where a field equals a particular value, use: ```js equals[field]=value ``` This syntax allows the search API to accept multiple field conditions in a single request. For example, to get all jobs with the name `Job name 1` and description `Job description 1`: ```js GET /operations-manager/jobs?equals[name]=Job name 1&equals[description]=Job description 1 ``` The API supports querying on nested properties using [dotted path notation](https://docs.mongodb.com/manual/core/document/#dot-notation). For example, to get all tasks started after `2021-11-18`: ```js GET /operations-manager/tasks?gt[metrics.start_time]=2021-11-18T23:59:59 ``` ### Workflow task query parameter syntax The `/operations-manager/jobs` and `/operations-manager/tasks` APIs can be invoked in workflows using the `getJobs` and `getTasks` workflow tasks, respectively. Query parameters are provided to these tasks in JSON object format using the `queryParameters` variable. To get all documents with a field equal to a particular value: ```json { "equals": { "field": "value" } } ``` To get all jobs with the name `Job name 1` and description `Job description 1`: ```json { "equals": { "name": "Job name 1", "description": "Job description 1" } } ``` ## Response format Operations Manager standardizes the top-level structure of all responses — both success and error — with the following fields: | Property | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | A human-readable message. Always populated with a string. | | `data` | Data directly related to the request. Always present; set to `null` when not applicable (as with error responses). | | `metadata` | Extra details about the response. An empty object when not available. Used for pagination information, detailed reports on failed imports, and input validation failures. | **Example response** ```json { "message": "Human readable message", "data": { "some": "data" }, "metadata": { "some": "metadata" } } ``` ## Basic examples To get all jobs with a name starting with `Job name prefix`: **API format** ```js GET /operations-manager/jobs?starts-with[name]=Job name prefix ``` **Workflow task format** ```json { "starts-with": { "name": "Job name prefix" } } ``` To get the IDs and names of all jobs started after November 18, 2021 (Unix epoch time format): **API format** ```js GET /operations-manager/jobs?include=_id,name>[metrics.start_time]=1637279999 ``` **Workflow task format** ```json { "include": "_id,name", "gt": { "metrics.start_time": "1637279999" } } ``` ## Search operators ### equals The `equals` operator returns documents with a field exactly matching the specified value. Operations Manager knows the field type, so you do not need to specify whether fields should be interpreted as dates, ObjectIds, booleans, etc. **API format** ```js GET /operations-manager/jobs?equals[name]=JobName ``` **Workflow task format** ```json { "equals": { "name": "JobName" } } ``` ### starts-with, ends-with, contains These three operators return documents with a field that starts with, ends with, or contains the specified string. For the `/jobs` API, the `description` property has special behavior when queried with `contains`. MongoDB text search syntax is supported, allowing efficient searching for complex expressions in the description field even as the jobs collection grows large. See the [MongoDB text search documentation](https://docs.mongodb.com/manual/text-search/) for details. **API format** ```js GET /operations-manager/jobs?starts-with[name]=NamePrefix GET /operations-manager/tasks?ends-with[name]=Suffix GET /operations-manager/jobs?contains[description]=InternalString ``` **Workflow task format** ```json { "starts-with": { "name": "NamePrefix" } } ``` ```json { "ends-with": { "name": "Suffix" } } ``` ```json { "contains": { "description": "InternalString" } } ``` ### in, not-in The `in` operator accepts a comma-separated list of options and returns documents with a field exactly equal to one of the specified options. For example, to get jobs with a name of `Name 1`, `Name 2`, or `Name 3`: ```js GET /operations-manager/jobs?in[name]=Name 1,Name 2,Name 3 ``` The `not-in` operator accepts the same format and returns documents with a field not equal to any of the specified options. If the search value contains a comma, percent-encode it as `%2C` to prevent Operations Manager from treating it as a delimiter. For example, to search for jobs named `Name,1` or `Name,2`: ```js GET /operations-manager/jobs?in[name]=Name%2C1,Name%2C2 ``` **API format** ```js GET /operations-manager/jobs?in[name]=EitherThis,OrThis,OrMaybeThis GET /operations-manager/tasks?not-in[description]=NotThis,NorThis ``` **Workflow task format** ```json { "in": { "name": "EitherThis,OrThis,OrMaybeThis" } } ``` ```json { "not-in": { "description": "NotThis,NorThis" } } ``` ### gt, lt, gte, lte These operators support comparison searches. Use `gt` for greater than, `lt` for less than, `gte` for greater than or equal to, and `lte` for less than or equal to. **API format** ```js GET /operations-manager/jobs?gt[metrics.progress]=0.5 GET /operations-manager/jobs?lte[metrics.start_time]=1637279999 ``` **Workflow task format** ```json { "gt": { "metrics.progress": 0.5 } } ``` ```json { "lte": { "metrics.start_time": "1669675620370" } } ``` ### ?q= The `?q=` query parameter supports more complex searches than the top-level query parameters, including logical combinations with `and`, `or`, and `not`. #### Create a JSON query object ```json { "equals": { "name": "my name" }, "starts-with": { "description": "Some desc prefix" } } ``` #### URL-encode the JSON object Use `encodeURIComponent` to encode the JSON: ``` %7B%22equals%22%3A%7B%22name%22%3A%22my%20name%22%7D%2C%22starts-with%22%3A%7B%22description%22%3A%22Some%20desc%20prefix%22%7D%7D ``` #### Pass the encoded value to ?q= ```js ?q=%7B%22equals%22%3A%7B%22name%22%3A%22my%20name%22%7D%2C%22starts-with%22%3A%7B%22description%22%3A%22Some%20desc%20prefix%22%7D%7D ``` ## Projection parameters Projection parameters limit the fields returned in the API response using either an inclusive list with `include` or an exclusive list with `exclude`. When specifying an inclusive list, the `_id` field is implicitly included even if not specified. To exclude it, add `&exclude=_id` alongside the `include` expression. ### include The `include` parameter accepts a comma-delineated list of property names to include in the response. **API format** ```js GET /operations-manager/jobs?include=name,description ``` **Workflow task format** ```json { "include": "name,description" } ``` **Response** ```json { "message": "Successfully retrieved items", "data": [ { "_id": "000000000000000000000000", "name": "Job 1", "description": "Job description 1" }, { "_id": "111111111111111111111111", "name": "Job 2", "description": "Job description 2" } ], "metadata": { "skip": 0, "limit": 100, "nextPageSkip": null, "previousPageSkip": null, "total": 2, "currentPageSize": 2 } } ``` ### exclude The `exclude` parameter specifies the set of properties to exclude from the response. **API format** ```js GET /operations-manager/jobs?include=name,description&exclude=_id ``` **Workflow task format** ```json { "include": "name,description", "exclude": "_id" } ``` **Response** ```json { "message": "Successfully retrieved items", "data": [ { "name": "Job 1", "description": "Job description 1" }, { "name": "Job 2", "description": "Job description 2" } ], "metadata": { "skip": 0, "limit": 100, "nextPageSkip": null, "previousPageSkip": null, "total": 2, "currentPageSize": 2 } } ``` ## Sort parameters Sort parameters arrange query results in a specified order using `?sort=` and `?order=<-1|1>`. Both parameters must be used together. * `order` must be `-1` or `1` * `sort` must be a valid field path within the queried document type When querying `/jobs`, you can use: ```js ?sort=metrics.start_time ``` The `sort` field must not be excluded from the response via projection parameters. ## Pagination parameters Use `?skip=` and `?limit=` to control the paging of results: * Both must be numbers * `limit` defaults to `100` and `skip` defaults to `0` ## Further reading For more information about Operations Manager APIs, see the [app-operations\_manager](https://apidocs.itential.com/2022.1/api/app-operations_manager/) section of the Itential API References. > Advanced query parameters, search operators, projection, sorting, and pagination for the Operations Manager jobs and tasks search APIs.