Skip to main content

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.

EndpointInputRuns
POST /api/v1.0/queries/executeA query in the request bodyThe query you send (ad hoc)
GET /api/v1.0/queries/{queryDefinitionId}/executeQueryQuery parameters in the URLA saved Query Definition, by its identifier
GET /api/v1.0/queries/{queryName}/executeQueryByNameQuery parameters in the URLA 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.

Related pages

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]=value for 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 @Instance or @User expression 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​

FieldRequiredDescription
instanceQueryYesThe main query. The request fails if it is missing.
relatedInstanceQueryDefinitionsNoRelated queries whose results are attached to every returned instance. Can nest.
sortOrdersNoIgnored by execute. Sort with instanceQuery.sortBy.
referenceTypeNoIgnored by execute. Used by saved queries and reference attributes. It has no relation to the relation direction.

InstanceQuery​

FieldRequiredDefaultDescription
instanceTypeNameYesNoneThe type to query. A blank value fails the request; an unknown type is reported as an error.
parentFiltersNoNoneList 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.
stateFilterNoNoneList of state names; a record matches when it is in any of them.
attributeFilterExpressionsNoNoneFilter groups. See Filter Values and Logic.
sortByNoNoneOne 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.
isSortByDescendingNofalseSort direction.
skipNo0Number of instances to skip.
takeNo100Number of instances to return.
includeTotalCountNotrueReturn totalCount.
getDataFromDBNofalseRead from the database instead of the search index. See Data source.
getAllAttributesNofalseReturn every attribute of the type.
attributesNoNoneNames of the attributes to return when getAllAttributes is false.
getAllowedOperationsNofalseInclude the operations the user may perform on each instance.
getAllowedActionsNofalseInclude the actions the user may trigger on each instance.
getOnlyActionableInstancesNofalseReturn 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​

FieldRequiredDescription
relatedInstanceQueryYesThe related query. The request fails if it is missing.
relatedInstanceQueryDefinitionsNoFurther related queries, one level deeper.
sortOrdersNoIgnored by execute.
referenceTypeNoIgnored by execute.

RelatedInstanceQuery​

FieldRequiredDefaultDescription
relationFiltersYesNoneOrdered 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.
stateFilterNoNoneState names applied to the returned instances.
attributeFilterExpressionsNoNoneFilter groups applied to the returned instances.
sortBy, isSortByDescendingNoNone, falseSorting of the related instances.
skip, takeNo0, 100Paging.
includeTotalCountNotrueReturn totalCount.
getCountOnlyNofalseReturn counts without the related instances.
getAllAttributes, attributesNofalse, NoneAttributes of the related instances to return.
getAllRelationAttributes, relationAttributesNofalse, NoneAttributes of the relation itself to return.
getAllowedOperations, getAllowedActionsNofalseInclude allowed operations or actions.

RelationFilter​

FieldRequiredDescription
typeNameYesType of the instances at this step.
relationTypeNameYesThe relation type to follow.
relationDirectionNoTo, 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, instanceIdsNoPin this step to specific instances.
stateFiltersNoState names for the instances at this step.
attributeFilterExpressionsNoConditions 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​

ObjectFields
AttributeFilterExpressionoperator (None, And, Or), orderIndex, attributeFilterConditions
AttributeFilterConditionattributeName, 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.

FieldDescription
totalCountNumber of matching instances after access filtering. Omitted when includeTotalCount is false.
skip, takeThe paging that was applied.
itemsThe 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​

  • skip defaults to 0 and take to 100. No upper limit is enforced, so keep take bounded (a few hundred).
  • Always provide a sort order when paging. Without one, results are ordered by Modified, newest first.
  • includeTotalCount (default true) returns the total number of matches. Set it to false to avoid the extra work when you do not need it.
  • getCountOnly is 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.

ValueBehavior
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.
trueAlways 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: true right after data has changed. It can be slower on large sets.
  • Related queries do not have this option.

Attributes​

SettingResult
getAllAttributes: trueEvery attribute of the type is returned.
getAllAttributes: false with attributesOnly the listed attributes are returned.
NeitherOnly 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.
  • totalCount is 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.

StatusWhen
400 Bad RequestInvalid 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 UnauthorizedNot authenticated, or the token has expired.
403 ForbiddenNone of the source instances (or a pinned instance) is accessible to the user.
404 Not FoundThe saved query does not exist, or the search service is unavailable.
429 Too Many RequestsToo many requests.
503 Service UnavailableA 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:

FieldDescription
typeThe kind of activity to return. All (the default) returns every kind except posted messages. Other values: ActionPromoted, GeolocationChanged, MessagePosted, TaskCreated, CloneCreated, MinorCreated, Modified.
startDate, endDateReturn 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.

FieldDescription
getOnlyConnectableInstancesSet to true to apply the restriction. It only has an effect when connectableInstanceQuery is also present.
connectableInstanceQuery.sourceInstanceIdThe instance the relation would start from. Leave it out when the source is a new, not yet created instance.
connectableInstanceQuery.relationTypeNameThe relation type that would be created.
connectableInstanceQuery.relationDirectionFrom if the instances being returned sit at the relation type's From end, To if they sit at its To end.
connectableInstanceQuery.validateDestinationTypeOnlyWhen 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.

SettingDefaultEffect
MaxAllowedParentFiltersCount20Maximum number of parent filters in one query. The value must be present: a missing value is read as 0, which rejects every parent filter.
EnableExpressionsInInstanceQueryfalseWhen 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.

NeedUse
Standard reads, paging, and simple navigation to related instances, in an OData-compatible clientOData ($filter, $select, $expand)
Related instances several levels deep, or with filters, state, sorting, and paging at each levelQuery 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 placesQuery Builder (saved queries)
Reading instances in a tool that expects a metadata-described OData modelOData

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.

  1. Look up exact names first: type, attribute, relation type, state, and picklist option names. Do not guess them. Resolve user names to user identifiers.
  2. Picklists: use the option display name, with Equals for single-select and Contains for multi-select. A mistyped name silently matches the wrong records.
  3. Lists: In and NotIn values are separated by new lines, never commas.
  4. Dates: send ISO 8601 values.
  5. States: use stateFilter with state names.
  6. Logic: use one connector style (And or Or) per level, and never None between two conditions.
  7. Relations: always send relationDirection explicitly (To or From).
  8. Recursion: nest a fixed number of levels, or query level by level until a level is empty, and state the depth searched.
  9. Freshness: use getDataFromDB: true right after the user has changed data.
  10. Payload: request only the attributes you need and keep take bounded.
  11. Empty results can mean no match, a wrong direction, a mistyped picklist name, a stale index, or no access. Check these before answering "none".