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.
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 need | Call | Use |
|---|---|---|
| Types | GET /types | typeName |
| Attributes of a type | GET /types/{typeName} | attributes[].name, type, picklistOptions (exact option names), isMultiselect |
| Relations of a type | GET /types/{typeName}/relatedTypes?relationDirection=To, then again with From | relationName as relationTypeName, relatedTypeName as typeName, and the direction you asked for as relationDirection |
| States of a type | GET /lifecycles/{lifecycleName} (the lifecycleName is on the type) | states[].name |
| A user's identifier | userValues[].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 type | You want | condition | firstValue |
|---|---|---|---|
| Text | Exact value | Equals | "X" |
| Text | Contains / starts with / ends with | Contains / StartsWith / EndsWith | "X" |
| Text, Numeric, Reference | Any of several values | In | "A\nB\nC" (separate with a new line, never a comma) |
| Numeric, Currency | Greater / less | GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual | "100" |
| Numeric, Currency, Date, DateTime | Between two values (inclusive) | Between | "A", and secondValue = "B" |
| Date | A date | Equals, LessThan, GreaterThan | "2026-01-31" |
| DateTime | A moment | GreaterThan, LessThan | "2026-01-31T09:30:00Z" |
| Date, DateTime | Today, last or next period | Today, LastOneWeek, LastOneMonth, LastOneYear, NextWeek, NextOneMonth, NextOneYear | none |
| Date, DateTime | Relative to now | GreaterThanOrEqual, LessThan, Between | "$StartOfToday(-7d)" |
| Picklist (single-select) | One option | Equals / NotEquals | "High" (option name) |
| Picklist (single-select) | Either of two options | two Equals joined by Or | one name each |
| Picklist (multi-select) | Has any / has all | Contains / Equals | "High,Critical" |
| User | Me | ContextUser | none |
| User | A specific user | Equals | the user's userId |
| Boolean | True or false | Equals | "true" or "false" |
| Reference | Linked to an instance | Equals / Contains | the instance's name |
| Any | Is empty / has a value | IsEmpty / IsNotEmpty | none |
| Built-in | Identifier | Equals on TrackingId or Name | "T-72-191" (Id is not valid) |
| Built-in | Created or modified time | GreaterThan on Created / Modified | ISO 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.
4. Add related records (optional)
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(usegetAllAttributes: trueonly if you do not know them). - Set
sortBywhenever order matters or you page withskipandtake. - For a count, use
take: 1and readtotalCount. - Use
getDataFromDB: trueright 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
| Goal | Condition |
|---|---|
| Overdue | DueDate LessThan "$StartOfToday()" |
| Due this month | DueDate Between, "$StartOfMonth()" and "$StartOfMonth(+1m)" |
| Created in the last week | Created LastOneWeek (no value) |
| Between fixed dates | Between, "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.
- Nest the same related definition inside itself a fixed number of levels (start with 5). Generate the nesting in code.
- Collect every instance from
relatedItemslevel by level. - If the deepest level still returned items, there may be more: continue from that level, or nest more levels, until a level is empty.
- 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
totalCountis the number of matches of the main query after access filtering (omitted whenincludeTotalCountisfalse).- Each item's attributes are in
attributes[], with the value in the field that matches itstype:textValue,dateValue,numericValue,booleanValue,arrayValue,userValues, orreferenceValues. - Related instances are in
items[].relatedItems.TypeName.items[], keyed by the type returned by the last relation filter. Each related item can have its ownrelatedItemsfor the next level. - An empty or missing related result means nothing was found or the signed-in user cannot access it.
- If
items.lengthequalstake, there may be more: page withskipor narrow the query. At related levelstakelimits rows across all parents, so raise it when there are many parents.
Fix problems
| Symptom | Cause | Fix |
|---|---|---|
| 400, attribute not associated with the type | Wrong attribute name, or Id used | Check GET /types/{typeName}; use Name or TrackingId instead of Id. |
| 400, invalid date | Not ISO 8601 | Use 2026-01-31, 2026-01-31T09:30:00Z, or a mnemonic. |
| 400, relation filter or type name required | A relation filter is missing relationTypeName or typeName | Fill both on every filter. |
| 400, related instance query required | A related definition has no relatedInstanceQuery | Add it. |
| 400, too many parent filters | More than 20 | Use fewer. |
| 400, invalid identifier | instanceId is not a GUID | Use a real GUID. |
| 400, invalid filter configuration | A condition has condition None | Set a real operator. |
| 400, invalid query | None joiner between two conditions | Use And or Or. |
| 400 on a relation | Direction Both, or the relation does not belong to the type | Use To or From. |
| 401 | Not signed in or token expired | Sign in again and retry once. |
| 403 | No access to the source or pinned instance | Do not retry; the user needs access. |
| 404 | Saved query not found, or search unavailable | Check the name, or retry later. |
| 429, 503 | Throttled, or a service is unavailable | Retry 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
| Mistake | Result | Prevention |
|---|---|---|
| Misspelled picklist name | Matches records with any value (Equals) or none (NotEquals) | Copy names from picklistOptions. |
| Wrong relation direction | Related items are empty | If empty, try the other direction before concluding there are none. |
Both in a later relation step | The step is skipped | Never use Both. |
Comma-separated In list | The text is treated as one value and matches nothing | Separate with \n. |
In on a picklist with several names | Fails or is meaningless | Use Equals with Or, or Contains. |
In value with spaces | The value can split into several terms | Prefer single-word values, or use Equals with Or. |
| Recursion too shallow | Deeper descendants are missing | Check the deepest level and report the depth. |
| Just-changed record missing | The search index lags | Use getDataFromDB: true. |
sortOrders or referenceType sent | Ignored | Use sortBy. |
Attribute not listed in attributes | Not returned | List the attributes you will read. |
Check before you send
- Names of types, attributes, relations, states, and picklist options come from step 1.
- Dates are ISO 8601 or a mnemonic; user values are identifiers or
ContextUser. Invalues use new lines;Betweenhas both values.- Every condition except the last has
AndorOr. - Every relation filter in a related query has
relationDirectionofToorFrom. sortByis set when paging, andtakeis bounded.attributeslists 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" }
}
}
}
}
}