Query Builder API
The Query Builder API runs a query and returns the matching instances, optionally with related instances attached. External applications, integrations, and automation use it for requests that need filtering and relationship traversal, including multi-level traversal that OData $expand cannot express.
| Endpoint | Input | Runs |
|---|---|---|
POST /api/v1.0/queries/execute | A query in the request body | The query you send (ad hoc) |
GET /api/v1.0/queries/{queryDefinitionId}/executeQuery | Query parameters in the URL | A saved Query Definition, by its identifier |
GET /api/v1.0/queries/{queryName}/executeQueryByName | Query parameters in the URL | A saved Query Definition, by its unique name |
All endpoints require an authenticated user, return a paged list of instances, and always apply the caller's access permissions. Download links of file attributes are returned as absolute API URLs.
- Value formats, operators, and logic: Filter Values and Logic
- Relation direction, nesting, and recursion: Relations, Nesting, and Recursion
Saved queries: executeQuery and executeQueryByName
Run a query that was created in the Query Builder.
GET /api/v1.0/queries/OpenProjectTasksByOwner/executeQueryByName?queryParameters[ProjectId]=7b1f3c0e-5d8a-4c55-9a27-0a6f3d2b9e11
GET /api/v1.0/queries/{queryDefinitionId}/executeQuery?queryParameters[ProjectId]=7b1f3c0e-5d8a-4c55-9a27-0a6f3d2b9e11
- Pass one
queryParameters[Name]=valuefor each query parameter, in the value format of its type. A parameter that is not supplied uses its saved default value. - The server does not evaluate a parameter's
@Instanceor@Userexpression for these endpoints; the caller must pass the value. - A dynamic attribute condition whose parameter resolves to a blank value is ignored, not reported as an error.
- A dynamic relation value must be one or more valid instance identifiers separated by commas; an invalid identifier fails the request.
- Instance Query definitions run as a plain instance query (no related items).
- Structured Query definitions run together with their related levels.
- Relation Query definitions need a source instance and cannot be run through these endpoints (the request fails). Use them from a Relation widget, or send an equivalent query to
execute. - The saved query's own paging and sorting settings apply.
Execute: request body
POST /api/v1.0/queries/execute takes an InstanceQueryDefinition.
InstanceQueryDefinition
| Field | Required | Description |
|---|---|---|
instanceQuery | Yes | The main query. The request fails if it is missing. |
relatedInstanceQueryDefinitions | No | Related queries whose results are attached to every returned instance. Can nest. |
sortOrders | No | Ignored by execute. Sort with instanceQuery.sortBy. |
referenceType | No | Ignored by execute. Used by saved queries and reference attributes. It has no relation to the relation direction. |
InstanceQuery
| Field | Required | Default | Description |
|---|---|---|---|
instanceTypeName | Yes | None | The type to query. A blank value fails the request; an unknown type is reported as an error. |
parentFilters | No | None | List of RelationFilter. At most 20 by default (configurable); more fails the request. The direction is always treated as From. Each needs typeName and relationTypeName. Several filters form an ordered ancestor chain; see Parent filters in detail. |
stateFilter | No | None | List of state names; a record matches when it is in any of them. |
attributeFilterExpressions | No | None | Filter groups. See Filter Values and Logic. |
sortBy | No | None | One sort key: a built-in attribute (State, Lifecycle, Creator, Modifier, Created, Modified) or an attribute name. With no sort key, results are ordered by Modified, newest first. |
isSortByDescending | No | false | Sort direction. |
skip | No | 0 | Number of instances to skip. |
take | No | 100 | Number of instances to return. |
includeTotalCount | No | true | Return totalCount. |
getDataFromDB | No | false | Read from the database instead of the search index. See Data source. |
getAllAttributes | No | false | Return every attribute of the type. |
attributes | No | None | Names of the attributes to return when getAllAttributes is false. |
getAllowedOperations | No | false | Include the operations the user may perform on each instance. |
getAllowedActions | No | false | Include the actions the user may trigger on each instance. |
getOnlyActionableInstances | No | false | Return only instances on which the user has a lifecycle action. |
Other fields (getOnlyConnectableInstances, connectableInstanceQuery, activityQuery) support specialized scenarios, and parentAttributes is obsolete. They are not needed for general querying.
RelatedInstanceQueryDefinition
| Field | Required | Description |
|---|---|---|
relatedInstanceQuery | Yes | The related query. The request fails if it is missing. |
relatedInstanceQueryDefinitions | No | Further related queries, one level deeper. |
sortOrders | No | Ignored by execute. |
referenceType | No | Ignored by execute. |
RelatedInstanceQuery
| Field | Required | Default | Description |
|---|---|---|---|
relationFilters | Yes | None | Ordered path from the source instance to the instances to return. At least one filter; each needs relationTypeName and typeName. The last filter's typeName is the returned type. |
stateFilter | No | None | State names applied to the returned instances. |
attributeFilterExpressions | No | None | Filter groups applied to the returned instances. |
sortBy, isSortByDescending | No | None, false | Sorting of the related instances. |
skip, take | No | 0, 100 | Paging. |
includeTotalCount | No | true | Return totalCount. |
getCountOnly | No | false | Return counts without the related instances. |
getAllAttributes, attributes | No | false, None | Attributes of the related instances to return. |
getAllRelationAttributes, relationAttributes | No | false, None | Attributes of the relation itself to return. |
getAllowedOperations, getAllowedActions | No | false | Include allowed operations or actions. |
RelationFilter
| Field | Required | Description |
|---|---|---|
typeName | Yes | Type of the instances at this step. |
relationTypeName | Yes | The relation type to follow. |
relationDirection | No | To, From, or Both. Defaults to From when omitted, so always send it. Both is not supported (it fails as the first step and is silently skipped in a later step). See Direction. |
instanceId, instanceIds | No | Pin this step to specific instances. |
stateFilters | No | State names for the instances at this step. |
attributeFilterExpressions | No | Conditions on the instances at this step. |
Fields such as isValueDynamic and dynamicValueParameterName (and the dynamic-value fields on conditions) apply to saved queries only. In a request to execute, send literal values.
AttributeFilterExpression and AttributeFilterCondition
| Object | Fields |
|---|---|
AttributeFilterExpression | operator (None, And, Or), orderIndex, attributeFilterConditions |
AttributeFilterCondition | attributeName, condition (the operator), firstValue, secondValue (for Between), operator (None, And, Or), orderIndex |
Operators: Contains, NotContains, Equals, NotEquals, StartsWith, EndsWith, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, Between, In, NotIn, IsEmpty, IsNotEmpty, ContextUser, Today, LastOneWeek, LastOneMonth, LastOneYear, NextWeek, NextOneMonth, NextOneYear. Value formats and combination rules are in Filter Values and Logic.
Response
The response is a paged list of instances.
| Field | Description |
|---|---|
totalCount | Number of matching instances after access filtering. Omitted when includeTotalCount is false. |
skip, take | The paging that was applied. |
items | The instances. |
Each instance contains id, name, instanceTypeName, state, lifecycle, created, modified, attributes, and, when requested, allowedOperations and allowedActions. Related instances are under relatedItems, keyed by the related type name; each entry is a paged list with relatedInstanceId, relatedInstanceName, relationTypeName, relationDirection, state, attributes, optional relationAttributes, and its own relatedItems.
An attribute has a name, a type, and the value in the field that matches its type: textValue, dateValue, numericValue, booleanValue, arrayValue, userValues, referenceValues, or fileValue.
id, name, instanceTypeName, state, created, and modified are always returned. Other attributes are returned only when getAllAttributes is true or they are listed in attributes; names that do not exist on the type are ignored.
Paging
skipdefaults to0andtaketo100. No upper limit is enforced, so keeptakebounded (a few hundred).- Always provide a sort order when paging. Without one, results are ordered by
Modified, newest first. includeTotalCount(defaulttrue) returns the total number of matches. Set it tofalseto avoid the extra work when you do not need it.getCountOnlyis available on related queries.- Related levels count relation rows across all source instances; see Relations, Nesting, and Recursion.
Data source
getDataFromDB selects where the matching records are read from.
| Value | Behavior |
|---|---|
false (default) | If the filters, the sort, and the requested attributes use only built-in attributes, the database is read directly. Otherwise the search index is used to filter and sort, and the matching records are validated against the database. |
true | Always reads the database. |
- The query is meant to return the same set of records either way. The difference is freshness: the search index is updated asynchronously, so a record that was just created or edited may not match a filter on a custom attribute until it is indexed.
- Use
getDataFromDB: trueright after data has changed. It can be slower on large sets. - Related queries do not have this option.
Attributes
| Setting | Result |
|---|---|
getAllAttributes: true | Every attribute of the type is returned. |
getAllAttributes: false with attributes | Only the listed attributes are returned. |
| Neither | Only the always-returned fields. |
Request only the attributes the caller needs.
Permissions
- Access control is always applied. The endpoints cannot be used to bypass it.
- Non-administrators see only instances they have access to (or instances of types that are open to everyone). Access policy rules are added to the filter, and the lists of allowed actions are limited by action-level policy.
totalCountis calculated after access filtering, so it cannot reveal hidden records.- Related queries leave out related instances the user cannot access. If some source instances are not accessible they are dropped silently and the rest are returned. If none is accessible, the request fails with 403 Forbidden. A pinned instance the user cannot access also gives 403. An empty related result can therefore mean "no access" as well as "no relation".
- Queries are limited to the caller's tenant.
Errors
The response body is the localized error message text.
| Status | When |
|---|---|
| 400 Bad Request | Invalid request: missing body, instanceQuery, instanceTypeName, or relation filter fields; too many parent filters; an invalid date format; an attribute that does not exist on the type (including Id); an invalid identifier; direction Both as the first step; a condition whose condition is None; a None connector between two conditions (database read); In with several names on a single-select picklist; invalid saved query JSON; running a saved Relation Query through executeQuery. Also the response for other unexpected errors. |
| 401 Unauthorized | Not authenticated, or the token has expired. |
| 403 Forbidden | None of the source instances (or a pinned instance) is accessible to the user. |
| 404 Not Found | The saved query does not exist, or the search service is unavailable. |
| 429 Too Many Requests | Too many requests. |
| 503 Service Unavailable | A required backend service is temporarily unavailable. |
Specialized options
These options of instanceQuery support specific features. Most queries do not need them.
Only actionable instances
getOnlyActionableInstances: true returns only instances on which the user has an applicable lifecycle action. Use it for work queues ("things I can act on"). It is combined with the other filters, and the user's permissions still apply.
Allowed operations and actions
getAllowedOperations: true and getAllowedActions: true add allowedOperations and allowedActions to each returned instance (and to related instances when set on the related query). The lists are trimmed by the user's permissions and by action-level access policy. Use them only when the caller must decide which buttons to show.
Activity query
activityQuery attaches the activity history of each returned instance (for example promotions, geolocation changes, clones, and modifications) in activities on the instance. Only these fields take effect:
| Field | Description |
|---|---|
type | The kind of activity to return. All (the default) returns every kind except posted messages. Other values: ActionPromoted, GeolocationChanged, MessagePosted, TaskCreated, CloneCreated, MinorCreated, Modified. |
startDate, endDate | Return only activities created between these two ISO 8601 date-times. Both must be set for the range to apply. |
Activities are returned newest first. The remaining fields of the object (instanceTypeNames, userIds, skip, take, sortBy, isSortByDescending) are not applied by execute.
{
"instanceQuery": {
"instanceTypeName": "Task",
"stateFilter": ["Open"],
"activityQuery": { "type": "ActionPromoted", "startDate": "2026-10-01T00:00:00Z", "endDate": "2026-10-31T23:59:59Z" }
}
}
Connectable instances
Used by "link an existing instance" pickers. It returns only the instances that the user may connect to a given source instance through a relation type.
| Field | Description |
|---|---|
getOnlyConnectableInstances | Set to true to apply the restriction. It only has an effect when connectableInstanceQuery is also present. |
connectableInstanceQuery.sourceInstanceId | The instance the relation would start from. Leave it out when the source is a new, not yet created instance. |
connectableInstanceQuery.relationTypeName | The relation type that would be created. |
connectableInstanceQuery.relationDirection | From if the instances being returned sit at the relation type's From end, To if they sit at its To end. |
connectableInstanceQuery.validateDestinationTypeOnly | When true, the check is limited to whether the destination type is allowed by the relation type. |
- The returned type (
instanceTypeName) must be allowed on the chosen end of the relation type; otherwise the request fails. - If the user may not connect the source instance (or, for a new instance, may not connect at its first state), the result is empty.
- Source and destination types must match the relation type; a mismatch is reported as an error.
Configuration settings
Two server settings affect queries. They are set per environment by an administrator of the deployment.
| Setting | Default | Effect |
|---|---|---|
MaxAllowedParentFiltersCount | 20 | Maximum number of parent filters in one query. The value must be present: a missing value is read as 0, which rejects every parent filter. |
EnableExpressionsInInstanceQuery | false | When true, @Instance, @User, and @Relation expressions inside filter values are evaluated by the server. See Expressions in filter values. |
Query Builder and OData
Protrak offers two ways to read instances over HTTP. Choose by what the question needs.
| Need | Use |
|---|---|
| Standard reads, paging, and simple navigation to related instances, in an OData-compatible client | OData ($filter, $select, $expand) |
| Related instances several levels deep, or with filters, state, sorting, and paging at each level | Query Builder (relatedInstanceQueryDefinitions) |
| Walking a self-referential relation (such as sub-tasks) | Query Builder, by nesting levels |
| Parent-chain filtering ("tasks of projects of program X") | Query Builder (parent filters) |
| Reusing a governed, saved filter in many places | Query Builder (saved queries) |
| Reading instances in a tool that expects a metadata-described OData model | OData |
OData $expand is bounded by configured limits: by default 5 expands per request, a nesting depth of 5, 10,000 total expanded items, and a maximum $top of 100 per expanded set. Query Builder has no nesting-depth limit, and each level has its own filter and paging, so it is the better fit for deep traversal. See the OData integration guide in the repository (docs/odata-integration-guide.md) for the OData settings.
Worked example
Open, high-priority tasks of one project that are due before 1 December 2026, together with their sub-tasks, two levels deep.
Request: POST /api/v1.0/queries/execute
{
"instanceQuery": {
"instanceTypeName": "Task",
"parentFilters": [
{
"typeName": "Project",
"relationTypeName": "ProjectToTask",
"instanceId": "7b1f3c0e-5d8a-4c55-9a27-0a6f3d2b9e11"
}
],
"stateFilter": ["Open", "InProgress"],
"attributeFilterExpressions": [
{
"operator": "None",
"orderIndex": 0,
"attributeFilterConditions": [
{ "attributeName": "Priority", "condition": "Equals", "firstValue": "High", "operator": "And", "orderIndex": 0 },
{ "attributeName": "DueDate", "condition": "LessThan", "firstValue": "2026-12-01", "operator": "None", "orderIndex": 1 }
]
}
],
"sortBy": "DueDate",
"isSortByDescending": false,
"skip": 0,
"take": 50,
"includeTotalCount": true,
"getDataFromDB": false,
"getAllAttributes": false,
"attributes": ["Priority", "DueDate"]
},
"relatedInstanceQueryDefinitions": [
{
"relatedInstanceQuery": {
"relationFilters": [
{ "typeName": "Task", "relationTypeName": "TaskToSubTask", "relationDirection": "To" }
],
"attributes": ["Priority"],
"skip": 0,
"take": 100
},
"relatedInstanceQueryDefinitions": [
{
"relatedInstanceQuery": {
"relationFilters": [
{ "typeName": "Task", "relationTypeName": "TaskToSubTask", "relationDirection": "To" }
],
"attributes": ["Priority"],
"take": 100
}
}
]
}
]
}
Response: 200 OK
{
"totalCount": 1,
"skip": 0,
"take": 50,
"items": [
{
"id": "c2d6a8f4-1e0b-4a8e-8f43-52a4d7c1b001",
"name": "T-72-191",
"instanceTypeName": "Task",
"state": { "name": "Open", "displayName": "Open" },
"created": "2026-09-02T06:41:10Z",
"modified": "2026-10-28T11:03:55Z",
"attributes": [
{ "name": "Priority", "type": "Picklist", "textValue": "High" },
{ "name": "DueDate", "type": "Date", "dateValue": "2026-11-20T00:00:00Z" }
],
"relatedItems": {
"Task": {
"totalCount": 1,
"skip": 0,
"take": 100,
"items": [
{
"relationTypeName": "TaskToSubTask",
"relationDirection": "To",
"relatedInstanceId": "9e41b7aa-3f6c-4d0f-b2a1-6c8d0e5f7002",
"relatedInstanceName": "T-72-205",
"state": { "name": "Open", "displayName": "Open" },
"attributes": [
{ "name": "Priority", "type": "Picklist", "textValue": "High" }
],
"relatedItems": {
"Task": { "totalCount": 0, "skip": 0, "take": 100, "items": [] }
}
}
]
}
}
}
]
}
The names, identifiers, and attribute values are illustrative. Only the fields relevant to the example are shown.
Tips for building requests
Tools that build queries dynamically should follow these rules (see also Query Request Cookbook), because several mistakes return plausible but wrong data instead of an error.
- Look up exact names first: type, attribute, relation type, state, and picklist option names. Do not guess them. Resolve user names to user identifiers.
- Picklists: use the option display name, with Equals for single-select and Contains for multi-select. A mistyped name silently matches the wrong records.
- Lists: In and NotIn values are separated by new lines, never commas.
- Dates: send ISO 8601 values.
- States: use
stateFilterwith state names. - Logic: use one connector style (And or Or) per level, and never
Nonebetween two conditions. - Relations: always send
relationDirectionexplicitly (ToorFrom). - Recursion: nest a fixed number of levels, or query level by level until a level is empty, and state the depth searched.
- Freshness: use
getDataFromDB: trueright after the user has changed data. - Payload: request only the attributes you need and keep
takebounded. - Empty results can mean no match, a wrong direction, a mistyped picklist name, a stale index, or no access. Check these before answering "none".