API: Query for Object(s)

The API: Query for Object(s) action searches Autotask and returns an array of matching entities. This is a low-level API action that makes a single API call, returning all results that match your query conditions.

Single API Call Action

This is a single API call action. You define the query conditions and the action makes one API call to retrieve the results. Learn more about the difference between workflow actions and single API call actions.

When to Use This Action

Use this action when:

• You need to find multiple entities matching certain criteria
• You want to iterate over results using the Iterate action
• You're building reports or processing batches of records

For a single result, use API: Query for One Object instead.

Configuration

Connection

Field	Description
Autotask Connection	Select the Autotask connection to use. If you have multiple connections, you can override the default.

Query

Field	Description
Autotask Entity Type to Query	The type of entity to search for (e.g., Ticket, Contact, Account).
Query Parameters	Filter conditions to find entities. Use AND/OR groups to build complex queries.
Sort Results	Order the results by one or more fields.

Options

Field	Description
Generate an exception if no results	Stop the workflow if no matching entities are found.
Generate an exception if more than one result	Stop the workflow if multiple entities match (rarely used with this action).

Advanced

Field	Description
Suppress Autotask API exceptions	If enabled, the workflow continues even if the Autotask API returns an error.

How to Query for Entities

1. Select Autotask Direct API: API: Query for multiple objects from the action dropdown
2. Choose the Autotask Entity Type to Query
3. Add query conditions to filter results
4. Configure sorting if needed
5. Store the results in a variable for use in later actions

Query Builder

Build filter conditions using:

• All of these (AND): All conditions must match
• Any of these (OR): At least one condition must match

For each condition:

1. Select a field (e.g., Status, AccountID, CreateDate)
2. Choose an operator (equals, contains, greater than, etc.)
3. Enter the value to match (supports template variables)

Nest groups to create complex logic combining AND and OR conditions.

Returned Variables

When you configure Store the results in Variable, an array of matching entities becomes available:

Variable	Type	Description
(root)	array	Array of matching entities, each with all properties and linked entities

Accessing Results

• {{custom.tickets[0].TicketNumber}}: First ticket's number
• {{custom.tickets.length}}: Number of results
• Use the Iterate action to loop through all results

Linked Entities

Each entity in the array includes related entities automatically. For example, each Ticket includes:

• The Ticket with all its properties
• Linked Contact with their properties
• Linked Account with their properties
• Linked Resource (assignee) with their properties

Example Use Cases

Find All Open Tickets for Account

Get all active tickets:

Setting	Value
Entity Type	Ticket
Conditions	AccountID equals {{custom.account.id}} AND Status not equal to 5
Sort	CreateDate (Descending)

Find All Contacts at Company

List contacts for a company:

Setting	Value
Entity Type	Contact
Condition	AccountID equals {{custom.account.id}}
Sort	LastName (Ascending)

Find Recent Tickets

Get tickets created in the last 7 days:

Setting	Value
Entity Type	Ticket
Condition	CreateDate greater than {{date add="-7 days"}}
Sort	CreateDate (Descending)

Working with Results

Using the Iterate Action

To process each result:

1. Query for multiple objects, storing in custom.tickets
2. Add an Iterate action over {{custom.tickets}}
3. Inside the iteration, access the current item as {{custom.currentItem}}

Checking Result Count

Use conditions to handle different scenarios:

• {{custom.tickets.length}} > 0: At least one result found
• {{custom.tickets.length}} == 1: Exactly one result
• {{custom.tickets.length}} > 10: Many results (may need filtering)

Difference from Query for One Object

Feature	Query Multiple	Query One
Returns	Array of objects	Single object
Best for	Search/list results	Known single result
Access syntax	{{custom.results[0].Property}}	{{custom.result.Property}}
Use with	Iterate action for looping	Direct property access

FAQs

What happens if no results match?

The variable contains an empty array ([]). Enable "Generate an exception if no results" to stop the workflow when this happens.

Is there a limit on results returned?

Autotask API queries have a maximum of 500 results per call. For larger datasets, you may need multiple queries with pagination.

How do I process each result?

Use the Iterate action to loop through the array and perform actions on each entity.

Can I query User-Defined Fields?

Yes. UDFs appear in the field selector with the prefix UDF:.

Related Documentation

• Autotask Entities: Overview of available entity types
• Auto-Expand Linked Objects: How linked entities are included
• API: Query for One Object: Return a single result