Skip to main content

Query Request Cookbook

This page shows how to write a POST /api/v1.0/queries/execute request, with ready-to-use examples for common tasks. For every field and default, see Query Builder API; for value formats, see Filter Values and Logic.

Copy names exactly

Type, attribute, relation, state, and picklist option names must match the system exactly. Several wrong values do not return an error: they return a plausible but wrong result. Look the names up first (step 1).

Build a request in five steps​

1. Look up the names you need​

All calls are authenticated GET requests under /api/v1.0.

You needCallUse
TypesGET /typestypeName
Attributes of a typeGET /types/{typeName}attributes[].name, type, picklistOptions (exact option names), isMultiselect
Relations of a typeGET /types/{typeName}/relatedTypes?relationDirection=To, then again with FromrelationName as relationTypeName, relatedTypeName as typeName, and the direction you asked for as relationDirection
States of a typeGET /lifecycles/{lifecycleName} (the lifecycleName is on the type)states[].name
A user's identifieruserValues[].userId on instances you already fetched. For "me", use ContextUser instead. Administrators can list users with GET /admin/users/lite.userId

2. Start from the minimal request​

{
"instanceQuery": {
"instanceTypeName": "Task",
"stateFilter": ["Open"],
"sortBy": "Modified",
"isSortByDescending": true,
"take": 50,
"attributes": ["Priority"]
}
}

Only instanceQuery.instanceTypeName is required. Add the parts you need in the next steps.

3. Add filters​

Pick the row that matches what you want, then fill in condition and firstValue.

Attribute typeYou wantconditionfirstValue
TextExact valueEquals"X"
TextContains / starts with / ends withContains / StartsWith / EndsWith"X"
Text, Numeric, ReferenceAny of several valuesIn"A\nB\nC" (separate with a new line, never a comma)
Numeric, CurrencyGreater / lessGreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual"100"
Numeric, Currency, Date, DateTimeBetween two values (inclusive)Between"A", and secondValue = "B"
DateA dateEquals, LessThan, GreaterThan"2026-01-31"
DateTimeA momentGreaterThan, LessThan"2026-01-31T09:30:00Z"
Date, DateTimeToday, last or next periodToday, LastOneWeek, LastOneMonth, LastOneYear, NextWeek, NextOneMonth, NextOneYearnone
Date, DateTimeRelative to nowGreaterThanOrEqual, LessThan, Between"$StartOfToday(-7d)"
Picklist (single-select)One optionEquals / NotEquals"High" (option name)
Picklist (single-select)Either of two optionstwo Equals joined by Orone name each
Picklist (multi-select)Has any / has allContains / Equals"High,Critical"
UserMeContextUsernone
UserA specific userEqualsthe user's userId
BooleanTrue or falseEquals"true" or "false"
ReferenceLinked to an instanceEquals / Containsthe instance's name
AnyIs empty / has a valueIsEmpty / IsNotEmptynone
Built-inIdentifierEquals on TrackingId or Name"T-72-191" (Id is not valid)
Built-inCreated or modified timeGreaterThan on Created / ModifiedISO 8601 date and time

A state is best filtered with stateFilter: ["Open"].

Joining conditions: set operator to And or Or on every condition except the last, which uses None. Keep one joiner style inside a group, and do not mix And and Or across three or more groups.

Add relatedInstanceQueryDefinitions. The last relation filter is the type you get back. Take relationDirection from step 1: To follows the relation from its From end to its To end, From goes the other way. Never use Both.

5. Choose what comes back​

  • List only the attributes you need in attributes (use getAllAttributes: true only if you do not know them).
  • Set sortBy whenever order matters or you page with skip and take.
  • For a count, use take: 1 and read totalCount.
  • Use getDataFromDB: true right after data was created or changed.

Common tasks​

Replace names and values with the ones from step 1.

Filter by text and a picklist​

{
"instanceQuery": {
"instanceTypeName": "Task",
"stateFilter": ["Open"],
"attributeFilterExpressions": [
{ "operator": "None", "orderIndex": 0, "attributeFilterConditions": [
{ "attributeName": "Name", "condition": "Contains", "firstValue": "Android", "operator": "And", "orderIndex": 0 },
{ "attributeName": "Priority", "condition": "Equals", "firstValue": "High", "operator": "None", "orderIndex": 1 }
] }
]
}
}

Match either of two values, then require a third condition​

"(High or Critical) and due before 1 December": the first group joins to the next group with And.

"attributeFilterExpressions": [
{ "operator": "And", "orderIndex": 0, "attributeFilterConditions": [
{ "attributeName": "Priority", "condition": "Equals", "firstValue": "High", "operator": "Or", "orderIndex": 0 },
{ "attributeName": "Priority", "condition": "Equals", "firstValue": "Critical", "operator": "None", "orderIndex": 1 }
] },
{ "operator": "None", "orderIndex": 1, "attributeFilterConditions": [
{ "attributeName": "DueDate", "condition": "LessThan", "firstValue": "2026-12-01", "operator": "None", "orderIndex": 0 }
] }
]

Filter by date​

GoalCondition
OverdueDueDate LessThan "$StartOfToday()"
Due this monthDueDate Between, "$StartOfMonth()" and "$StartOfMonth(+1m)"
Created in the last weekCreated LastOneWeek (no value)
Between fixed datesBetween, "2026-01-01" and "2026-01-31"

List only my records​

{ "attributeName": "Owner", "condition": "ContextUser", "operator": "None", "orderIndex": 0 }

Match a list of values​

{ "attributeName": "Team", "condition": "In", "firstValue": "Alpha\nBeta\nGamma", "operator": "None", "orderIndex": 0 }

List the records under a parent​

Known parent identifier:

{ "instanceQuery": { "instanceTypeName": "Task",
"parentFilters": [ { "typeName": "Project", "relationTypeName": "ProjectToTask", "instanceId": "7b1f3c0e-5d8a-4c55-9a27-0a6f3d2b9e11" } ] } }

Parent known by name or tracking id: replace instanceId with "attributeFilterExpressions" on the parent filter (for example TrackingId Equals "PRJ-014"). Several parent filters form an ordered chain: topmost ancestor first, direct parent last.

Get the children (or parents) of one record​

"Sub-tasks of T-72-191": select the record by TrackingId (or Name), then attach the related level. Use "relationDirection": "From" and the parent type to go upward instead.

{
"instanceQuery": {
"instanceTypeName": "Task",
"attributeFilterExpressions": [
{ "operator": "None", "orderIndex": 0, "attributeFilterConditions": [
{ "attributeName": "TrackingId", "condition": "Equals", "firstValue": "T-72-191", "operator": "None", "orderIndex": 0 }
] }
],
"attributes": []
},
"relatedInstanceQueryDefinitions": [
{ "relatedInstanceQuery": {
"relationFilters": [ { "typeName": "Task", "relationTypeName": "TaskToSubTask", "relationDirection": "To" } ],
"attributes": ["Priority"], "take": 200 } }
]
}

The sub-tasks are in items[0].relatedItems.Task.items. If TrackingId finds nothing, try Name.

Follow a path of several relations​

"Documents of the deliverables of a project": list the steps in order; the last step is returned.

"relationFilters": [
{ "typeName": "Deliverable", "relationTypeName": "ProjectToDeliverable", "relationDirection": "To" },
{ "typeName": "Document", "relationTypeName": "DeliverableToDocument", "relationDirection": "To" }
]

Get all descendants (for example every sub-task)​

A query follows exactly the levels you nest; there is no "until the end" option.

  1. Nest the same related definition inside itself a fixed number of levels (start with 5). Generate the nesting in code.
  2. Collect every instance from relatedItems level by level.
  3. If the deepest level still returned items, there may be more: continue from that level, or nest more levels, until a level is empty.
  4. Report the depth you searched together with the result.

Two levels, to show the shape:

"relatedInstanceQueryDefinitions": [
{ "relatedInstanceQuery": { "relationFilters": [ { "typeName": "Task", "relationTypeName": "TaskToSubTask", "relationDirection": "To" } ], "attributes": ["Name"], "take": 500 },
"relatedInstanceQueryDefinitions": [
{ "relatedInstanceQuery": { "relationFilters": [ { "typeName": "Task", "relationTypeName": "TaskToSubTask", "relationDirection": "To" } ], "attributes": ["Name"], "take": 500 } }
] }
]

Read the results​

  • totalCount is the number of matches of the main query after access filtering (omitted when includeTotalCount is false).
  • Each item's attributes are in attributes[], with the value in the field that matches its type: textValue, dateValue, numericValue, booleanValue, arrayValue, userValues, or referenceValues.
  • Related instances are in items[].relatedItems.TypeName.items[], keyed by the type returned by the last relation filter. Each related item can have its own relatedItems for the next level.
  • An empty or missing related result means nothing was found or the signed-in user cannot access it.
  • If items.length equals take, there may be more: page with skip or narrow the query. At related levels take limits rows across all parents, so raise it when there are many parents.

Fix problems​

SymptomCauseFix
400, attribute not associated with the typeWrong attribute name, or Id usedCheck GET /types/{typeName}; use Name or TrackingId instead of Id.
400, invalid dateNot ISO 8601Use 2026-01-31, 2026-01-31T09:30:00Z, or a mnemonic.
400, relation filter or type name requiredA relation filter is missing relationTypeName or typeNameFill both on every filter.
400, related instance query requiredA related definition has no relatedInstanceQueryAdd it.
400, too many parent filtersMore than 20Use fewer.
400, invalid identifierinstanceId is not a GUIDUse a real GUID.
400, invalid filter configurationA condition has condition NoneSet a real operator.
400, invalid queryNone joiner between two conditionsUse And or Or.
400 on a relationDirection Both, or the relation does not belong to the typeUse To or From.
401Not signed in or token expiredSign in again and retry once.
403No access to the source or pinned instanceDo not retry; the user needs access.
404Saved query not found, or search unavailableCheck the name, or retry later.
429, 503Throttled, or a service is unavailableRetry later with a back-off.

Fix the specific cause and resend; do not retry the same body.

Mistakes that return wrong results without an error​

MistakeResultPrevention
Misspelled picklist nameMatches records with any value (Equals) or none (NotEquals)Copy names from picklistOptions.
Wrong relation directionRelated items are emptyIf empty, try the other direction before concluding there are none.
Both in a later relation stepThe step is skippedNever use Both.
Comma-separated In listThe text is treated as one value and matches nothingSeparate with \n.
In on a picklist with several namesFails or is meaninglessUse Equals with Or, or Contains.
In value with spacesThe value can split into several termsPrefer single-word values, or use Equals with Or.
Recursion too shallowDeeper descendants are missingCheck the deepest level and report the depth.
Just-changed record missingThe search index lagsUse getDataFromDB: true.
sortOrders or referenceType sentIgnoredUse sortBy.
Attribute not listed in attributesNot returnedList the attributes you will read.

Check before you send​

  1. Names of types, attributes, relations, states, and picklist options come from step 1.
  2. Dates are ISO 8601 or a mnemonic; user values are identifiers or ContextUser.
  3. In values use new lines; Between has both values.
  4. Every condition except the last has And or Or.
  5. Every relation filter in a related query has relationDirection of To or From.
  6. sortBy is set when paging, and take is bounded.
  7. attributes lists only what you need.

JSON Schema (optional)​

Use this schema to validate a request's shape before sending it. It cannot check that names exist or that values are formatted correctly.

Show the JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Query Builder execute request",
"type": "object",
"required": ["instanceQuery"],
"additionalProperties": false,
"properties": {
"instanceQuery": { "$ref": "#/$defs/instanceQuery" },
"relatedInstanceQueryDefinitions": {
"type": "array",
"items": { "$ref": "#/$defs/relatedDefinition" }
}
},
"$defs": {
"connector": { "enum": ["None", "And", "Or"] },
"conditionOperator": {
"enum": [
"Contains", "NotContains", "Equals", "NotEquals", "StartsWith", "EndsWith",
"GreaterThan", "GreaterThanOrEqual", "LessThan", "LessThanOrEqual", "Between",
"In", "NotIn", "IsEmpty", "IsNotEmpty", "ContextUser",
"Today", "LastOneWeek", "LastOneMonth", "LastOneYear",
"NextWeek", "NextOneMonth", "NextOneYear"
]
},
"condition": {
"type": "object",
"required": ["attributeName", "condition"],
"additionalProperties": false,
"properties": {
"attributeName": { "type": "string", "minLength": 1 },
"condition": { "$ref": "#/$defs/conditionOperator" },
"firstValue": { "type": "string" },
"secondValue": { "type": "string" },
"operator": { "$ref": "#/$defs/connector" },
"orderIndex": { "type": "integer", "minimum": 0 }
},
"if": { "properties": { "condition": { "const": "Between" } }, "required": ["condition"] },
"then": { "required": ["firstValue", "secondValue"] }
},
"expression": {
"type": "object",
"required": ["attributeFilterConditions"],
"additionalProperties": false,
"properties": {
"operator": { "$ref": "#/$defs/connector" },
"orderIndex": { "type": "integer", "minimum": 0 },
"attributeFilterConditions": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/condition" }
}
}
},
"stringList": { "type": "array", "items": { "type": "string", "minLength": 1 } },
"parentFilter": {
"type": "object",
"required": ["typeName", "relationTypeName"],
"additionalProperties": false,
"properties": {
"typeName": { "type": "string", "minLength": 1 },
"relationTypeName": { "type": "string", "minLength": 1 },
"instanceId": { "type": "string", "format": "uuid" },
"instanceIds": { "type": "array", "items": { "type": "string", "format": "uuid" } },
"stateFilters": { "$ref": "#/$defs/stringList" },
"attributeFilterExpressions": { "type": "array", "items": { "$ref": "#/$defs/expression" } }
}
},
"relationFilter": {
"type": "object",
"required": ["typeName", "relationTypeName", "relationDirection"],
"additionalProperties": false,
"properties": {
"typeName": { "type": "string", "minLength": 1 },
"relationTypeName": { "type": "string", "minLength": 1 },
"relationDirection": { "enum": ["From", "To"] },
"instanceId": { "type": "string", "format": "uuid" },
"instanceIds": { "type": "array", "items": { "type": "string", "format": "uuid" } },
"stateFilters": { "$ref": "#/$defs/stringList" },
"attributeFilterExpressions": { "type": "array", "items": { "$ref": "#/$defs/expression" } }
}
},
"instanceQuery": {
"type": "object",
"required": ["instanceTypeName"],
"additionalProperties": false,
"properties": {
"instanceTypeName": { "type": "string", "minLength": 1 },
"parentFilters": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/parentFilter" } },
"stateFilter": { "$ref": "#/$defs/stringList" },
"attributeFilterExpressions": { "type": "array", "items": { "$ref": "#/$defs/expression" } },
"sortBy": { "type": "string" },
"isSortByDescending": { "type": "boolean" },
"skip": { "type": "integer", "minimum": 0 },
"take": { "type": "integer", "minimum": 1 },
"includeTotalCount": { "type": "boolean" },
"getDataFromDB": { "type": "boolean" },
"getAllAttributes": { "type": "boolean" },
"attributes": { "$ref": "#/$defs/stringList" },
"getAllowedOperations": { "type": "boolean" },
"getAllowedActions": { "type": "boolean" },
"getOnlyActionableInstances": { "type": "boolean" }
}
},
"relatedQuery": {
"type": "object",
"required": ["relationFilters"],
"additionalProperties": false,
"properties": {
"relationFilters": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/relationFilter" } },
"stateFilter": { "$ref": "#/$defs/stringList" },
"attributeFilterExpressions": { "type": "array", "items": { "$ref": "#/$defs/expression" } },
"sortBy": { "type": "string" },
"isSortByDescending": { "type": "boolean" },
"skip": { "type": "integer", "minimum": 0 },
"take": { "type": "integer", "minimum": 1 },
"includeTotalCount": { "type": "boolean" },
"getCountOnly": { "type": "boolean" },
"getAllAttributes": { "type": "boolean" },
"attributes": { "$ref": "#/$defs/stringList" },
"getAllRelationAttributes": { "type": "boolean" },
"relationAttributes": { "$ref": "#/$defs/stringList" },
"getAllowedOperations": { "type": "boolean" },
"getAllowedActions": { "type": "boolean" }
}
},
"relatedDefinition": {
"type": "object",
"required": ["relatedInstanceQuery"],
"additionalProperties": false,
"properties": {
"relatedInstanceQuery": { "$ref": "#/$defs/relatedQuery" },
"relatedInstanceQueryDefinitions": {
"type": "array",
"items": { "$ref": "#/$defs/relatedDefinition" }
}
}
}
}
}