Overview of query parameters

When you execute a Cloud API call using only the endpoint (as in GET /activities), the response payload has a default response. You may want to refine the default by:

  • Retrieve an effective-dated resource "as of" a certain date
  • Specifying a custom set of properties
  • Filtering out resources that do not meet a given criteria
  • Sorting the resources
  • Modify how pagination behaves, which can include:
    • Limiting the number of resources returned in each payload
    • Advancing to the next set of resources
    • Retrieving a count of the total number of resources that meet the query's criteria

You can refine the response using query parameters. A query parameter is an expression added to the HTTP request that modifies the default response.

Query parameters are specified at the end of the URL after a question mark (?). The general syntax is:

<URL>?<queryParameterExpressionList>

For example:

  • GET /common/v1/activities?fields=*all
  • GET /common/v1/activities?filter=escalated:eq:false

Specifying multiple query parameters

A Cloud API call can include multiple query parameter expressions. Separate each query parameter expression using an ampersand (&). For example:

  • GET /common/v1/activities?fields=*all&filter=escalated:eq:false

Included resources

With GETs, you can use the include query parameter to include resources related to the primary resources of the response. You can also use query parameters to specify a custom set of properties for included resources, filter out included resources that do not meet a given criteria, sort the included resources, and so on. For more information, see Query parameters for included resources.

Field-specific query parameters may not be supported for all fields

If you attempt to use a field-specific query parameter on a field that does not support that parameter, Cloud API returns a 400 Bad Request error and an error message. For example, when working with activities, the sort parameter is not supported for the escalationDate field. If you execute: GET /common/v1/activities?sort=escalationDate, Cloud API provides an error message similar to the following:

"message": "The sort column 'escalationDate' is not a valid option. The valid 
        sort options are [assignedUser, dueDate, escalated, priority, status, subject], 
        optionally prefixed with '-' to indicate a descending sort."

Viewing query parameter definitions

For every endpoint, the API definition provides descriptions of the query parameters supported by that endpoint.

Query parameters in Swagger UI

In Swagger UI, the query parameters information is hidden by default. To show the descriptions, click the endpoint's operation button (such as the GET button for GET /activities). The query parameter descriptions appear under the endpoint.

Parameter definitions

The Parameters section describes each query parameter.

Supported parameters

The Responses section include a Model tab. This tab provides information about the fields that support particular query parameters. For example, you can sort results on some fields, but not all of them. The fields that support sorting appear in the model with the text "sortable": true.