You can choose a builtin or saved query as a starting point for filtering results by selecting it with queryKey. If you don't specify a queryKey, the query will start with no constraints.

For example, many applications have builtin queries like "active" or "open" to find only active or enabled results. To use a queryKey, specify it like this:

{
  ...
  "queryKey": "active",
  ...
}

The table below shows the keys to use to select builtin queries and your saved queries, but you can also use any query you run via the web UI as a starting point. You can find the key for a query by examining the URI after running a normal search.

You can use these keys to select builtin queries and your configured saved queries:

You can apply custom constraints by passing a dictionary in constraints. This will let you search for specific sets of results (for example, you may want show only results with a certain state, status, or owner).

If you specify both a queryKey and constraints, the builtin or saved query will be applied first as a starting point, then any additional values in constraints will be applied, overwriting the defaults from the original query.

Different endpoints support different constraints. The constraints this method supports are detailed below. As an example, you might specify constraints like this:

{
  ...
  "constraints": {
    "authorPHIDs": ["PHID-USER-1111", "PHID-USER-2222"],
    "flavors": ["cherry", "orange"],
    ...
  },
  ...
}

This API endpoint supports these constraints:

Constants supported by the status constraint:

Constants supported by the icons constraint:

Constants supported by the colors constraint:

Use order to choose an ordering for the results.

Either specify a single key from the builtin orders (these are a set of meaningful, high-level, human-readable orders) or specify a custom list of low-level columns.

To use a high-level order, choose a builtin order from the table below and specify it like this:

{
  ...
  "order": "newest",
  ...
}

These builtin orders are available:

You can choose a low-level column order instead. To do this, provide a list of columns instead of a single key. This is an advanced feature.

In a custom column order:

• each column may only be specified once;
• each column may be prefixed with - to invert the order;
• the last column must be a unique column, usually id; and
• no column other than the last may be unique.

To use a low-level order, choose a sequence of columns and specify them like this:

{
  ...
  "order": ["color", "-name", "id"],
  ...
}

These low-level columns are available:

Objects matching your query are returned as a list of dictionaries in the data property of the results. Each dictionary has some metadata and a fields key, which contains the information about the object that most callers will be interested in.

For example, the results may look something like this:

{
  ...
  "data": [
    {
      "id": 123,
      "phid": "PHID-WXYZ-1111",
      "fields": {
        "name": "First Example Object",
        "authorPHID": "PHID-USER-2222"
      }
    },
    {
      "id": 124,
      "phid": "PHID-WXYZ-3333",
      "fields": {
        "name": "Second Example Object",
        "authorPHID": "PHID-USER-4444"
      }
    },
    ...
  ]
  ...
}

This result structure is standardized across all search methods, but the available fields differ from application to application.

These are the fields available on this object type:

By default, only basic information about objects is returned. If you want more extensive information, you can use available attachments to get more information in the results (like subscribers and projects).

Generally, requesting more information means the query executes more slowly and returns more data (in some cases, much more data). You should normally request only the data you need.

To request extra data, specify which attachments you want in the attachments parameter:

{
  ...
  "attachments": {
    "subscribers": true
  },
  ...
}

This example specifies that results should include information about subscribers. In the return value, each object will now have this information filled out in the corresponding attachments value:

{
  ...
  "data": [
    {
      ...
      "attachments": {
        "subscribers": {
          "subscriberPHIDs": [
            "PHID-WXYZ-2222",
          ],
          "subscriberCount": 1,
          "viewerIsSubscribed": false
        }
      },
      ...
    },
    ...
  ],
  ...
}

These attachments are available:

Queries are limited to returning 100 results at a time. If you want fewer results than this, you can use limit to specify a smaller limit.

If you want more results, you'll need to make additional queries to retrieve more pages of results.

The result structure contains a cursor key with information you'll need in order to fetch the next page of results. After an initial query, it will usually look something like this:

{
  ...
  "cursor": {
    "limit": 100,
    "after": "1234",
    "before": null,
    "order": null
  }
  ...
}

The limit and order fields are describing the effective limit and order the query was executed with, and are usually not of much interest. The after and before fields give you cursors which you can pass when making another API call in order to get the next (or previous) page of results.

To get the next page of results, repeat your API call with all the same parameters as the original call, but pass the after cursor you received from the first call in the after parameter when making the second call.

If you do things correctly, you should get the second page of results, and a cursor structure like this:

{
  ...
  "cursor": {
    "limit": 5,
    "after": "4567",
    "before": "7890",
    "order": null
  }
  ...
}

You can now continue to the third page of results by passing the new after cursor to the after parameter in your third call, or return to the previous page of results by passing the before cursor to the before parameter. This might be useful if you are rendering a web UI for a user and want to provide "Next Page" and "Previous Page" links.

If after is null, there is no next page of results available. Likewise, if before is null, there are no previous results available.