[New] Enhanced filtering for custom task types in Search API

English Forum Developers & API Changelog
1

[New] Enhanced filtering for custom task types in Search API

Summary

Two new filtering capabilities are now available on the Search tasks in a workspace endpoint (GET /workspaces/{workspace_gid}/tasks/search):

  • resource_subtype now accepts "custom" as a value, allowing you to scope search results to custom tasks only.
  • A new parameter, custom_types.{CUSTOM_TYPE_GID}.custom_type_status_option.gid, allows you to filter custom tasks by a specific custom type and status option.

Previously, retrieving custom tasks required fetching broader result sets and filtering client-side. These parameters move that filtering to the API, reducing the number of requests and the amount of data your application needs to process.

Note: The search endpoint is only available to users in a premium workspace (Starter, Advanced, Enterprise, and Enterprise+ tiers), or members of a premium team within a workspace. Requests made with non-premium credentials will return a 402 Payment Required error. See Premium access in the API reference for details.

Who is this for?

Developers using GET /workspaces/{workspace_gid}/tasks/search who work with custom task types. Specifically useful for:

  • Workflow automation — Identify custom tasks of a specific type that have reached a specific status to trigger downstream actions.
  • Custom reporting — Query only the custom task types relevant to a dashboard without filtering out standard tasks, milestones, or approvals after the fact.
  • Integration syncing — Query for specific custom task updates within a workspace to keep external systems in sync.

Usage

New and updated parameters

Parameter New or Existing Details
resource_subtype Existing Now accepts "custom" in addition to "default_task", "milestone", and "approval".
custom_types.{CUSTOM_TYPE_GID}.custom_type_status_option.gid New Query parameter. Filters custom tasks by a specific custom type GID and a specific status option GID within that type. Not required. Type: string.

Validation rules

  • When using custom_types.{CUSTOM_TYPE_GID}.custom_type_status_option.gid, resource_subtype must be set to "custom". Otherwise the API returns a 400 Bad Request.
  • You cannot pass custom_fields.{status_field_gid}.value for a status field at the same time as custom_types.{CUSTOM_TYPE_GID}.custom_type_status_option.gid. A validation error will be returned to prevent conflicting filter logic.

Example requests

Search for all custom tasks (any type):

// GET /workspaces/12345/tasks/search?resource_subtype=custom

Search for custom tasks of a specific type and status:

// GET /workspaces/12345/tasks/search?resource_subtype=custom&custom_types.67890.custom_type_status_option.gid=15753

Example response

{
  "data": [
    {
      "gid": "1234567890",
      "resource_type": "task",
      "name": "Q2 Product Spec",
      "resource_subtype": "custom"
    },
    {
      "gid": "9876543210",
      "resource_type": "task",
      "name": "Vendor Onboarding Request",
      "resource_subtype": "custom"
    }
  ]
}

Error responses

Scenario Error message
Invalid resource_subtype value resource_subtype: Must be one of {default_task, approval, milestone, custom}, not: {invalid_value}
custom_types params used without resource_subtype=custom resource_subtype: resource_subtype must be 'custom' when custom_types params are specified
Invalid custom type GID Not a valid custom type GID: {gid}
Invalid status option GID custom_types.{CUSTOM_TYPE_GID}.custom_type_status_option.gid: invalid GID for status option {provided_gid}
Conflict with custom_fields status filter custom_fields.{status_field_gid}.value: Cannot specify custom_fields filter for status field when using custom_types params

Important behaviors to be aware of

Eventual consistency: Search results reflect Asana’s search index, which can lag behind actual data by 10–60 seconds under normal conditions. A custom task whose status was just updated may not appear in filtered results immediately. If your use case requires immediate consistency after writing, use Get multiple tasks instead.

Pagination: Search results are not stable — repeating the same query may return results in a different order. Standard cursor-based pagination is not supported on this endpoint. To paginate manually, sort by creation time and exclude records already retrieved in subsequent queries. Page size is limited to a maximum of 100 items via the limit parameter.

Timeline

This is available now.

Resources

2 Likes
2

Very nice API addition!

I would just note generally that the term “custom task” is a new phrase we’ve not really seen used before now (which makes sense since custom task types are pretty new).

Obviously it’s a shorthand way to refer to a task having a custom task type set on it. Just found it interesting and worth calling out since we’ll likely see this shorthand phrase used a lot more going forward, given how totally awesome custom task types are! (cc: @Richard_Sather :slight_smile: )

3 Likes
3

Thanks a lot for the comment @Phil_Seeman, you are right! The shorthand refers to tasks with custom task types, I just changed the headline to be more clear about this referring to custom type tasks being available for filtering in the Search API.

Thanks for highlighting, and indeed, this is a great API addition, we know it serves many usecases for partners and developers.

Enjoy it!

3 Likes