[New] Advanced Search for Projects

English Forum Developers & API Changelog
, ,
1

[New] Advanced Search for Projects

Finding specific projects via the API previously required fetching large lists and filtering client-side. The new Advanced Project Search endpoint allows you to query projects directly by name, membership, custom fields, and date ranges, using the same filtering capabilities available in Asana’s web app search.

Who is affected?

This change applies to developers building integrations for Asana Starter, Advanced, Enterprise, and Enterprise+ customers. Users on the Personal (free) plan or guests will receive a 402 Payment Required error if they attempt to access this endpoint.

Usage Information

The new endpoint is a GET request available at the workspace level. While all parameters are optional, you must specify at least one search filter to receive a valid response.

This endpoint requires the projects:read OAuth scope. Requests made without this scope will be rejected

Endpoint

GET /workspaces/{workspace_gid}/projects/search

Filter Parameters (Selected Examples)

The following table highlights some of the most commonly used filter parameters. This is not an exhaustive list.

Field Name Type Description
text string Full-text search on the project name.
members.any string Comma-separated list of user IDs to filter by project members.
created_on date Filter by an exact match of the created date (e.g., 2024-01-01).
created_at.after datetime Filter for projects created after a specific ISO 8601 datetime.
custom_fields.{gid}.value string/int Filter by exact matches in custom fields.
sort_by enum Sort by due_date, created_at, completed_at, or modified_at (default).

Custom field filtering goes beyond exact value matching. You can also use custom_fields.{gid}.is_set to check if a field has any value, starts_with, ends_with, and contains for text fields, and less_than and greater_than for number fields. Note that searching for multiple exact matches and filtering on multi-enum custom fields are not currently supported. See the full custom field parameters reference for details.

For the complete set of query parameters — including additional date filters, completion status, owner, archived state, and more — see the full parameter reference.

Filtering & Sorting Behavior

  • Membership Filtering: Use members.any to filter for projects where the specified user IDs are members, mirroring the “Project Member” filter found in the Asana web app.
  • Flexible Date Formats: Parameters for creation and completion support both date strings (e.g., 2024-01-01) and high-precision ISO 8601 datetime strings (e.g., 2024-01-01T09:00:00Z).
  • Sorting: You can sort results by due_date, created_at, or completed_at. Sorting by modified_at is supported and is the default behavior. Note that filtering by modification time is not currently supported.

Limits & Pagination

The traditional pagination available elsewhere in the Asana API is not available for this endpoint. The limit parameter defaults to 100 results, which is also the maximum number of results returned per request. You may specify a lower limit (e.g., limit=5) if you only need the top results.

Example Request

// GET /workspaces/12345/projects/search?text=Launch&created_at.after=2024-01-01T09:00:00Z&limit=10
{
  "data": [
    {
      "gid": "98765",
      "resource_type": "project",
      "name": "Global Product Launch"
    },
    {
      "gid": "45678",
      "resource_type": "project",
      "name": "Beta Launch Feedback"
    }
  ]
}

Important: Consistency, Result Stability and Limits

This endpoint is powered by Asana’s search infrastructure. Changes made to projects — whether through the web app or the API — are forwarded to the search index asynchronously. This process typically takes between 10 and 60 seconds under normal operation, and may take longer during production incidents. A project you just created or modified may not appear in search results immediately.

Because of this, the search endpoint is not suited for workflows that require immediate consistency after writes. If you need read-your-write behavior, use Get multiple projects instead.

Additionally, search results may not be consistent. Repeating the same query multiple times may return results in a different order, even if no underlying data has changed. Plan your integration accordingly and avoid relying on result ordering for deduplication or state tracking.

Standard rate limits apply. You may receive a 429 Too Many Requests response if any limit is exceeded.

Timeline

This endpoint is now live and available for use in all production environments for eligible workspaces.

Key Resources

3 Likes