Asana API

Getting access, Developing, Testing

Back to Asana

Search Tasks In A Workspace

To mirror the functionality of the Asana web app's advanced search feature, the Asana API has a task search endpoint that allows you to build complex filters to find and retrieve the exact data you need.

Premium access

Like the Asana web product's advance search feature, this search endpoint will only be available to premium Asana users. A user is premium if any of the following is true:

  • The workspace in which the search is being performed is a premium workspace - The user is a member of a premium team inside the workspace

Even if a user is only a member of a premium team inside a non-premium workspace, search will allow them to find data anywhere in the workspace, not just inside the premium team. Making a search request using credentials of a non-premium user will result in a 402 Payment Required error.

Pagination

Search results are not stable; repeating the same query multiple times may return the data in a different order, even if the data do not change. Because of this, the traditional pagination available elsewhere in the Asana API is not available here. However, you can paginate manually by sorting the search results by their creation time and then modifying each subsequent query to exclude data you have already seen. Page sizes are limited to a maximum of 100 items, and can be specified by the limit query parameter.

Eventual consistency

Changes in Asana (regardless of whether they’re made though the web product or the API) are forwarded to our search infrastructure to be indexed. This process can take between 10 and 60 seconds to complete under normal operation, and longer during some production incidents. Making a change to a task that would alter its presence in a particular search query will not be reflected immediately. This is also true of the advanced search feature in the web product.

Rate limits

You may receive a 429 Too Many Requests response if you hit any of our rate limits.

Custom field parameters

| Parameter name | Custom field type | Accepted type | |---|---|---| | custom_fields.{gid}.is_set | All | Boolean | | custom_fields.{gid}.value | Text | String | | custom_fields.{gid}.value | Number | Number | | custom_fields.{gid}.value | Enum | Enum option ID | | custom_fields.{gid}.starts_with | Text only | String | | custom_fields.{gid}.ends_with | Text only | String | | custom_fields.{gid}.contains | Text only | String | | custom_fields.{gid}.less_than | Number only | Number | | custom_fields.{gid}.greater_than | Number only | Number |

For example, if the gid of the custom field is 12345, these query parameter to find tasks where it is set would be custom_fields.12345.is_set=true. To match an exact value for an enum custom field, use the gid of the desired enum option and not the name of the enum option: custom_fields.12345.value=67890.

Not Supported: searching for multiple exact matches of a custom field, searching for multi-enum custom field

Note: If you specify projects.any and sections.any, you will receive tasks for the project and tasks for the section. If you're looking for only tasks in a section, omit the projects.any from the request.

Input

type: object properties: parameters: type: object properties: workspace_gid: type: string description: Globally unique identifier for the workspace or organization. opt_pretty: type: boolean description: >- Provides “pretty” output. Provides the response in a “pretty” format. In the case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable only to use this during debugging. opt_fields: type: array items: type: string description: >- Defines fields to return. Some requests return *compact* representations of objects in order to conserve resources and complete the request more efficiently. Other times requests return more information than you may need. This option allows you to list the exact set of fields that the API should be sure to return for the objects. The field names should be provided as paths, described below. The id of included objects will always be returned, regardless of the field options. text: type: string description: Performs full-text search on both task name and description resource_subtype: type: string enum: - default_task - milestone default: milestone description: Filters results by the task's resource_subtype assignee.any: type: string description: Comma-separated list of user identifiers assignee.not: type: string description: Comma-separated list of user identifiers portfolios.any: type: string description: Comma-separated list of portfolio IDs projects.any: type: string description: Comma-separated list of project IDs projects.not: type: string description: Comma-separated list of project IDs projects.all: type: string description: Comma-separated list of project IDs sections.any: type: string description: Comma-separated list of section or column IDs sections.not: type: string description: Comma-separated list of section or column IDs sections.all: type: string description: Comma-separated list of section or column IDs tags.any: type: string description: Comma-separated list of tag IDs tags.not: type: string description: Comma-separated list of tag IDs tags.all: type: string description: Comma-separated list of tag IDs teams.any: type: string description: Comma-separated list of team IDs followers.not: type: string description: Comma-separated list of user identifiers created_by.any: type: string description: Comma-separated list of user identifiers created_by.not: type: string description: Comma-separated list of user identifiers assigned_by.any: type: string description: Comma-separated list of user identifiers assigned_by.not: type: string description: Comma-separated list of user identifiers liked_by.not: type: string description: Comma-separated list of user identifiers commented_on_by.not: type: string description: Comma-separated list of user identifiers due_on.before: type: string format: date description: ISO 8601 date string due_on.after: type: string format: date description: ISO 8601 date string due_on: type: string format: date nullable: true description: ISO 8601 date string or `null` due_at.before: type: string format: date-time description: ISO 8601 datetime string due_at.after: type: string format: date-time description: ISO 8601 datetime string start_on.before: type: string format: date description: ISO 8601 date string start_on.after: type: string format: date description: ISO 8601 date string start_on: type: string format: date nullable: true description: ISO 8601 date string or `null` created_on.before: type: string format: date description: ISO 8601 date string created_on.after: type: string format: date description: ISO 8601 date string created_on: type: string format: date nullable: true description: ISO 8601 date string or `null` created_at.before: type: string format: date-time description: ISO 8601 datetime string created_at.after: type: string format: date-time description: ISO 8601 datetime string completed_on.before: type: string format: date description: ISO 8601 date string completed_on.after: type: string format: date description: ISO 8601 date string completed_on: type: string format: date nullable: true description: ISO 8601 date string or `null` completed_at.before: type: string format: date-time description: ISO 8601 datetime string completed_at.after: type: string format: date-time description: ISO 8601 datetime string modified_on.before: type: string format: date description: ISO 8601 date string modified_on.after: type: string format: date description: ISO 8601 date string modified_on: type: string format: date nullable: true description: ISO 8601 date string or `null` modified_at.before: type: string format: date-time description: ISO 8601 datetime string modified_at.after: type: string format: date-time description: ISO 8601 datetime string is_blocking: type: boolean description: Filter to incomplete tasks with dependents is_blocked: type: boolean description: Filter to tasks with incomplete dependencies has_attachment: type: boolean description: Filter to tasks with attachments completed: type: boolean description: Filter to completed tasks is_subtask: type: boolean description: Filter to subtasks sort_by: type: string enum: - due_date - created_at - completed_at - likes - modified_at default: modified_at description: >- One of `due_date`, `created_at`, `completed_at`, `likes`, or `modified_at`, defaults to `modified_at` sort_ascending: type: boolean default: false description: Default `false` required: - workspace_gid title: Parameters

Output

type: object properties: data: type: array items: type: object properties: gid: description: Globally unique identifier of the resource, as a string. type: string readOnly: true example: '12345' x-insert-after: false resource_type: description: The base type of this resource. type: string readOnly: true example: task x-insert-after: gid name: description: The name of the task. type: string example: Bug Task resource_subtype: type: string description: >- The subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning. The resource_subtype `milestone` represent a single moment in time. This means tasks with this subtype cannot have a start_date. enum: - default_task - milestone - section - approval example: default_task