Asana

1. Overview

Asana is a leading team collaboration and work management tool designed to help teams plan, organize, and track work progress, providing clear visibility from daily tasks to strategic projects.

Through GoInsight's Asana node, you can seamlessly integrate powerful project management capabilities into your automated workflows, achieving full lifecycle management of Asana's core resources. This enables you to automate task creation, project updates, team collaboration, and other tedious operations, significantly improving team efficiency. Specific capabilities include:

• Workspace and Team Management: Automatically retrieve workspaces and team lists, providing a foundation for subsequent operations.
• Full Project Lifecycle Management: Support for creating, querying, updating, and deleting projects, enabling automated project setup and maintenance.
• Granular Task and Subtask Operations: Easily create, query, update, and delete tasks and subtasks, and add comments, tags, or associate them with different projects.
• User and Resource Management: Retrieve user lists within workspaces or query specific user details.

2. Prerequisites

Before using this node, you need to meet the following conditions:

• Have a valid Asana account.
• To create and configure credentials (typically a Personal Access Token), you may need appropriate account permissions.

3. Credentials

For detailed guidance on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Project, Subtask, Tag, Task, Task Comment, Task Project, Task Tag, Team, User, and Workspace.

Operation Details

Create a Project

Creates a new Asana project in a workspace.

Idempotency Warning:

• This action is NOT idempotent. Repeating the same request can create duplicate projects.
• To avoid duplicates, search or list projects in the workspace before creating a new one.

Input Parameters:

• WorkspaceGId: The globally unique identifier (GID) of the Asana workspace where the project will be created.
• ProjectName: The project name to create. It is generally a short sentence fragment that fits on a line in the UI for maximum readability.

Options:

• OptFields: ⚠️Advanced Options: Comma-separated list of optional project fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).
• AdditionalFields: Optional additional Asana project fields. Include any valid Asana project fields (e.g., color, due_on, notes, privacy_setting).

Output:

• Project (object): Created Asana project object in dict format.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Project

Delete an Asana project by its GID. This action is irreversible.

⚠️ WARNING: This operation is PERMANENT and CANNOT BE UNDONE. Deleted project is immediately removed from Asana projects.

Input Parameters:

• ProjectGid: The globally unique identifier (GID) of the Asana project to delete.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if the operation failed; empty when successful. Includes specific Asana API error details for troubleshooting. WARNING: Project deletion cannot be undone.

Get Many Projects

Retrieves compact project records for all projects in an Asana workspace using cursor-based pagination.

Maps to Asana API GET /workspaces/{workspace_gid}/projects (required scope: projects:read).

Key points:

• Use workspace_gid from Get Many Workspaces.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Asana returns compact project objects by default (gid, resource_type, name); OptFields selects additional fields.
• Use smaller limit values first, then continue with NextPage.offset if more projects are needed.

Input Parameters:

• WorkspaceId: Globally unique identifier for the workspace or organization whose projects should be listed.

Options:

• Limit: Results per page. The number of project objects to return per page. Valid range: 1-100. Defaults to 30.
• Offset: Offset token for the next page returned by the API. Leave empty for the first page. For subsequent pages, copy the offset value from the previous response's NextPage field. You can only pass in an offset that was returned via a previously paginated request.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional project properties to include in the response. By default, Asana returns a compact project (gid, resource_type, name). Nested fields use dot notation (e.g., owner.name, team.name); gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Projects (object-array): Compact Asana project records returned by GET /workspaces/{workspace_gid}/projects.
• NextPage (object): Pagination cursor metadata for the next page when more projects are available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Asana API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get a Project

Retrieves details for a single Asana project by project GID.

What: Fetches project metadata from Asana, including common fields such as name, notes, dates, owner, team, workspace, members, followers, and permalink.

Input Parameters:

• ProjectGid: The globally unique identifier (GID) of the Asana project to retrieve.

Options:

• OptFields: ⚠️Advanced Options: Comma-separated list of optional project fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Project (object): Retrieved Asana project object in dict format. Includes the requested project fields when available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update a Project

Updates metadata for an existing Asana project by project GID.

Defensive calling strategy:

• Verify the project_gid exists with Get_a_Project before updating.
• Send only the fields that should change; omitted fields are left unchanged.
• Use additional_fields for supported Asana project fields that are not exposed as top-level parameters.

Update Strategy:

• This is an incremental update (PATCH-like behavior).
• Only fields you provide will be updated; omitted fields remain unchanged.
• To clear a field, explicitly set it to null or empty string (depending on field type).

Input Parameters:

• ProjectGid: The globally unique identifier (GID) of the Asana project to update.

Options:

• Name: The name of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability.
• Notes: Free-form textual information associated with the project. Use this to provide context, instructions, or documentation for the project.
• Archived: Whether to archive the project. Archived projects are hidden from most views but can be restored.
• AdditionalFields: Additional Asana project fields to update. Examples include archived, color, due_on, owner, team, and custom_fields.

Output:

• Project (object): Updated Asana project object in dict format.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create a Subtask

Creates a new Asana subtask under a parent task.

Idempotency Warning:

• This action is NOT idempotent. Repeating the same request can create duplicate subtasks.
• To avoid duplicates, list existing subtasks on the parent task before creating a new one.

Input Parameters:

• ParentTaskId: The GID (Global ID, Asana's unique identifier) of the parent Asana task under which the subtask will be created. This is required. GID is a numeric string, typically 15-16 digits.
• Name: The name of the subtask to be created. This is required.

Options:

• AdditionalFields: Optional additional Asana task fields for the subtask. Include any valid Asana task fields (e.g., assignee, completed, due_on, liked, notes, workspace).
• OptFields: ⚠️Advanced Options: Comma-separated list of optional subtask fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Subtask (object): Created Asana subtask object in dict format.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Subtasks

Retrieves multiple subtasks under the specified Asana parent task.

Key points:

• Use ParentTaskGid from Get a Task, Get Many Tasks, Search Tasks, or a task creation response.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Use smaller Limit values first, then continue with NextPage.offset if more subtasks exist.
• Use OptFields to keep subtask responses compact.

Input Parameters:

• ParentTaskId: The globally unique identifier (GID) of the parent Asana task whose subtasks should be listed.

Options:

• Limit: Maximum number of subtasks to retrieve per page. Valid range: 1-100.
• Offset: Pagination token for retrieving the next page of results. Leave empty for the first page. For subsequent pages, copy the 'offset' value from the 'NextPage' field in the previous response. This is automatically provided by Asana's API and does not need to be manually constructed.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional subtask fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Subtasks (object-array): Retrieved Asana subtask objects in list format.
• NextPage (object): Pagination cursor metadata for the next page when more subtasks are available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500+=System error (may retry).
• ErrorMessage (string): Detailed error message if the operation failed; empty when successful. Includes Asana API error details for debugging.

Create a Tag

Creates a tag is a label that can be attached to any task in Asana. It exists in a single workspace or organization.

Idempotency Warning:

• This action is NOT idempotent. Repeating the same request can create duplicate tags.
• To avoid duplicates, list or search tags in the workspace before creating a new one.

Input Parameters:

• WorkspaceGid: The globally unique identifier (GID) of the Asana workspace where the tag will be created.
• TagName: The tag name to create. It is a short sentence fragment that fits on a line in the UI for maximum readability.

Options:

• Color: Asana tag color value, Valid values: "light-pink", "dark-pink", "light-red", "dark-red", "light-orange", "dark-orange", "light-yellow", "dark-yellow", "light-green", "dark-green", "light-teal", "dark-teal", "light-blue", "dark-blue", "light-purple", "dark-purple", "null".
• Notes: Optional free-form notes stored on the tag itself. Use this to add stable context for why the tag exists, how it should be applied, or internal governance guidance that helps agents and users interpret the tag. Leave empty when the tag name is self-explanatory or when the information belongs on a task, project, or comment instead.
• Followers: An array of strings identifying users. These can either be the string "me", an email, or the gid of a user.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional tag fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned. See https://developers.asana.com/docs/inputoutput-options.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Tag (object): The complete created tag object from Asana API containing the following fields: gid, name, color, created_at, workspace, resource_type.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): he original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Tag

Delete an Asana tag by its GID. This action is irreversible.

Idempotency Warning:

• This action is destructive and cannot be safely repeated as a no-op guarantee.
• Deleting an already-deleted tag may return 404 because the tag no longer exists.
• After a timeout or unclear upstream result, retrieve the tag before retrying to confirm whether it still exists.

Input Parameters:

• TagGid: The globally unique identifier (GID) of the Asana tag to delete.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Tags

Retrieves tags from an Asana workspace using cursor-based pagination.

Key points:

• Use WorkspaceGid from Get Many Workspaces; do not pass a workspace name.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Use smaller Limit values first, then continue with NextPage.offset if more tags exist.
• Use OptFields to request only the tag fields needed by the next step.

Input Parameters:

• WorkspaceGid: The Asana workspace or organization GID whose tags should be listed.

Options:

• Limit: Number of projects to return per page. Defaults to 30, maximum 100.
• Offset: Offset token from a previous paginated response. Empty value means the first page.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional subtask fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: When set to true, returns a response with indentation and line breaks (pretty-printed). When set to false (default), returns a compact response optimized for machine processing and reduced bandwidth usage. Accepts boolean values.

Output:

• Tags (object-array): Retrieved Asana tag objects in list format.
• NextPage (object): Cursor metadata for the next page when more tags are available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create a Task

Creates a new Asana task in a workspace.

Idempotency Warning:

• This action is NOT idempotent. Repeating the same request can create duplicate tasks.
• To avoid duplicates, search or list tasks before creating a new one.

Input Parameters:

• WorkspaceGid: The globally unique identifier (GID) of the Asana workspace where the task will be created.
• TagName: The task name to create. This is generally a short sentence fragment that fits on a line in the UI for maximum readability.

Options:

• OptFields: ⚠️Advanced Options: Comma-separated list of optional task fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).
• ProjectGids: Optional list of project GIDs to add the new task to.
• AdditionalFields: Optional additional Asana task fields. Include any valid Asana task fields (e.g., assignee, due_on, notes).

Output:

• Task (object): The complete created task object from Asana API containing the following core fields: gid, name, notes, created_at, modified_at, completed, assignee, due_on, workspace, projects, tags.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Task

Delete an Asana task by its GID. This action is irreversible.

⚠️ WARNING: This operation is PERMANENT and CANNOT BE UNDONE. Deleted task is immediately removed from Asana tasks.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task to delete.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Tasks

Retrieves tasks from Asana using supported workspace, project, section, tag, or assignee filters with cursor-based pagination.

Key points:

• Provide the narrowest supported filter available, such as ProjectGid, SectionGid, TagGid, or AssigneeGid, to avoid broad task dumps.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Use smaller Limit values first and page with NextPage.offset when more tasks are needed.
• Use OptFields to request only the task fields needed by the next step.

Input Parameters:

• ProjectGId: The globally unique identifier (GID) of the Asana project whose tasks should be listed.

Options:

• Limit: Maximum number of tasks to retrieve per page. Valid range: 1-100.
• Offset: Pagination token for retrieving the next page of results. Leave empty for the first page. For subsequent pages, copy the 'offset' value from the 'NextPage' field in the previous response. This is automatically provided by Asana's API and does not need to be manually constructed.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional task fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).
• AdditionalFields: Additional fields to include in the request. Only one of assignee or workspace is required when filtering by assignee or workspace.

Output:

• Tasks (object-array): Array of task objects. Each object contains: gid (string, task ID), name (string, task name), notes (string, task notes), assignee (object with assignee info), completed (boolean), due_on (string, due date), created_at (string, creation timestamp), modified_at (string, modification timestamp).
• NextPage (object): Pagination cursor info for fetching next page. Contains 'offset' (cursor value) and 'uri' (direct API path). Pass the 'offset' value to the Offset parameter for the next request.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates an upstream API business error (e.g., invalid token, resource not found).

Get a Task

Retrieves details for a single Asana task by task GID.

What: Fetches task metadata from Asana, including common fields such as name, notes, assignee, completion state, due date, projects, tags, workspace, and permalink.

Input Parameters:

• TaskGId: The globally unique identifier (GID) of the Asana task to retrieve.

Options:

• OptFields: ⚠️Advanced Options: Comma-separated list of optional task fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Task (object): Retrieved Asana task object in dict format. Includes the requested task fields when available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search Tasks

Searches for tasks in the specified Asana workspace using advanced search filters. Supports complex query syntax for filtering by name, status, assignee, due date, custom fields, and more. Returns a flat array of matching tasks. Requires premium workspace access.

NOTE: Search results are not stable; repeating the same query may return results in different order.

Input Parameters:

• WorkspaceGid: The globally unique identifier (GID) of the Asana workspace to search tasks in.

Options:

• Limit: Maximum number of results to return per page. Range: 1-100, default is 20.
• SortBy: Sort field. One of due_date, created_at, completed_at, likes, relevance, or modified_at, defaults to modified_at.
• SortAscending: Sort direction. True for ascending, False for descending. Defaults to False.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional task fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).
• AdditionalFields: A dictionary of additional fields to include in the response. Include any valid Asana task fields (e.g., text, resource_subtype, assignee.any, projects.all, tags.all, created_by.any, due_on, start_on, created_on, modified_on, completed_on, has_attachment, completed, is_subtask).

Output:

• Tasks (object-array): A list of matching Asana task objects.
• Pagination (object): Pagination metadata object containing the following fields: limit, has_more, next_page_token.
• Summary (string): A one-sentence summary of the search results to prevent context flooding.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update a Task

Updates metadata for an existing Asana task by task GID.

Defensive calling strategy:

• Verify the task_gid exists with Get_a_Task before updating.
• Send only the fields that should change; omitted fields are left unchanged.
• Use additional_fields for supported Asana task fields that are not exposed as top-level parameters.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task to update.

Options:

• Name: The name of the task. This is generally a short sentence fragment that fits on a line in the UI for maximum readability.
• Notes: Free-form textual information associated with the task. Use this to provide context, instructions, or documentation for the task.
• AdditionalFields: Additional Asana task fields to update. Includes any valid Asana task update fields (e.g., assignee, completed, due_on, liked).

Output:

• Task (object): Updated Asana task object in dict format.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add a Task Comment

Creates a comment story on an Asana task.

Idempotency Warning:

• Cannot specify text or html_text with sticker_name.
• If the stricker_name is not specified, then either text or html_text must be provided, but not both.
• This action is NOT idempotent. Repeating the same request can create duplicate task comments.
• After a timeout or unclear upstream result, list the task's stories before retrying.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task where the comment should be added.

Options:

• Text: The plain text of the comment to add. Cannot be used with html_text. text and html_text are mutually exclusive.
• HtmlText: HTML formatted text for a comment. This will not include the name of the creator. Cannot be used with text. text and html_text are mutually exclusive.
• IsPinned: Optional flag indicating whether the story should be pinned on the task.
• StickerName: The name of the sticker to add to the comment.

Output:

• Comment (object): Created Asana story/comment object in dict format.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Remove a Task Comment

Delete an Asana task comment story by its story GID. Only the user who created the story can delete it.

Idempotency Warning:

• This action is destructive and not safely repeatable. A successful delete permanently removes the comment story.
• Repeating the same request after a successful delete usually returns 404 because the story no longer exists.
• After a timeout, retrieve the task's stories before retrying to confirm whether the comment still exists.

Input Parameters:

• StoryGid: The globally unique identifier (GID) of the Asana story (comment) to delete.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add a Task Project

Adds an existing Asana task to an existing Asana project, optionally placing it in a section or position.

Idempotency Warning:

• The task-project association itself is unique, so repeating the same basic addProject request should not create duplicate project memberships.
• This endpoint can also reorder a task that is already in the project. Repeating a positioned request can move the task again if the anchor tasks or section state changed.
• After a timeout or unclear upstream result, read the task memberships or project task order before retrying.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task to add to the project.
• ProjectGid: The globally unique identifier (GID) of the Asana project to add the task to.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Remove a Task Project

Remove an Asana task from a project.

Idempotency Warning:

• This action is logically idempotent for the task-project membership: once removed, repeating the same request should not remove anything else.
• Asana may return a client error if the task is already absent from the project, the task no longer exists, or the project GID is wrong.
• After a timeout, read the task's project memberships before retrying.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task to remove from the project.
• ProjectGid: The globally unique identifier (GID) of the Asana project to remove from the task.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Asana API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if the operation failed; empty when successful. Includes specific Asana API error details for troubleshooting.

Add a Task Tag

Adds an existing Asana tag to an existing Asana task.

Idempotency Warning:

• This action is effectively idempotent for the same task_gid and tag_gid because a task cannot have duplicate copies of the same tag.
• After a timeout or unclear upstream result, read the task's tags before retrying to confirm whether the tag was already added.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task to modify.
• TagGid: The globally unique identifier (GID) of the Asana tag to add to the task.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Remove a Task Tag

Remove an Asana tag from a task.

Idempotency Warning:

• This action is logically idempotent for the task-tag relationship: once removed, repeating the same request should not remove anything else.
• Asana may return a client error if the task is already missing the tag, the task no longer exists, or the tag GID is wrong.
• After a timeout, read the task's tags before retrying.

Input Parameters:

• TaskGid: The globally unique identifier (GID) of the Asana task to remove the tag from.
• TagGid: The globally unique identifier (GID) of the Asana tag to remove from the task.

Output:

• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Asana API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. Possible values: 0=not reached upstream, 200=success, 400=bad request, 401=unauthorized, 404=not found, 429=rate limited, 5xx=server error.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if the operation failed; empty when successful. Includes specific Asana API error details for troubleshooting.

Get Many Teams

Retrieves teams from an Asana organization using cursor-based pagination.

Key points:

• Use WorkspaceGid from Get Many Workspaces and ensure it is an organization workspace.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Use Limit and Offset to page through large organizations.
• Use OptFields to keep team responses compact.

Input Parameters:

• WorkspaceGid: GID (Global ID) of the workspace to get teams from. This is a required identifier. You can obtain workspace GIDs by calling the Get Many Workspaces action. Example: "1234567890123456"

Options:

• Limit: Maximum number of teams to retrieve per page. Valid range: 1-100.
• Offset: Pagination cursor (offset token from Asana API response). Leave empty for the first page. For subsequent pages, use the 'next_page.offset' value from the previous response.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional team fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned. See https://developers.asana.com/docs/inputoutput-options.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).
• Archived: Controls whether archived teams are included in the returned team list. Set to false for normal workflows that only need active teams, such as choosing where to create a project or filtering current team-scoped resources. Set to true when auditing historical structure, migrating old data, or looking up teams that may have been archived.

Output:

• Teams (object-array): Retrieved Asana team objects in list format.
• NextPage (object): Pagination cursor metadata for the next page when more teams are available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream Asana API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if the operation failed; empty when successful. Includes Asana API error details for debugging.

Get Many Users

Retrieves users from an Asana workspace or organization using cursor-based pagination.

Key points:

• Use WorkspaceGid from Get Many Workspaces; do not pass a workspace name.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Keep Limit small for broad user directories, then page with NextPage.offset as needed.
• Use OptFields to request only the user fields needed by the next step.

Input Parameters:

• WorkspaceGid: The globally unique identifier (GID) of the Asana workspace whose users should be listed.

Options:

• Limit: Maximum number of users to retrieve per page. Valid range: 1-100.
• Offset: Pagination token for retrieving the next page of results. Leave empty for the first page. For subsequent pages, copy the 'offset' value from the 'NextPage' field in the previous response. This is automatically provided by Asana's API and does not need to be manually constructed.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional user fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Users (object-array): Array of user objects.
• NextPage (object): Pagination cursor metadata for the next page when more users are available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if the operation failed; empty when successful. Includes Asana API error details for debugging.

Get a User

Retrieves details for a single Asana user by user GID or me.

What: Fetches user metadata from Asana, including common fields such as name, email, photo, and workspaces.

Input Parameters:

• UserGid: The globally unique identifier (GID) of the Asana user to retrieve, or me for the authenticated user.

Options:

• OptFields: ⚠️Advanced Options: Comma-separated list of optional user fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• User (object): Retrieved Asana user object in dict format. Includes the requested user fields when available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get Many Workspaces

Retrieves workspaces accessible to the authenticated Asana user using cursor-based pagination.

Key points:

• Use this first when you need a workspace GID for other Asana list, get, create, update, or search actions.
• Provide exactly one credential: access_token or oauth2_access_token, not both.
• Use smaller limit values for first-time calls to avoid returning more workspace metadata than needed.
• Continue pagination by copying NextPage.offset into the Offset input; do not construct offset manually.

Options:

• Limit: Maximum number of workspaces to retrieve per page. Valid range: 1-100.
• Offset: Pagination token for retrieving the next page of results. Leave empty for the first page. For subsequent pages, copy the 'offset' value from the 'NextPage' field in the previous response. This is automatically provided by Asana's API and does not need to be manually constructed.
• OptFields: ⚠️Advanced Options: Comma-separated list of optional workspace fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Workspaces (object-array): Retrieved Asana workspace objects in list format.
• NextPage (object): Pagination cursor metadata for the next page when more workspaces are available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get a Workspace

Retrieves details for a single Asana workspace by workspace GID.

What: Fetches workspace metadata from Asana, including common fields such as name, resource type, email domains, and organization status.

Input Parameters:

• WorkspaceGId: The globally unique identifier (GID) of the Asana workspace to retrieve.

Options:

• OptFields: ⚠️Advanced Options: Comma-separated list of optional workspace fields in the response. By default, this endpoint returns a compact resource that excludes certain optional properties. To include them, provide a comma-separated list of field paths (e.g., assignee.name, followers.email). Nested fields use dot notation; gid of included objects is always returned.
• OptPretty: ⚠️Advanced Options: Whether to format the output (for ease of human reading). Once enabled, it will increase the response volume and processing time. It is only recommended to use it during debugging. For Agent workflows in the production environment, please keep it disabled (the default setting).

Output:

• Workspace (object): Retrieved Asana workspace object in dict format. Includes the requested workspace fields when available.
• Hint (string): Guidance on what to do next when an error occurs. Provides actionable steps for Agent to resolve the issue.
• Retryable (bool): Whether the request can be retried with the same parameters. True for transient errors (timeout, rate limit, 5xx), False for parameter/auth/not-found errors.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success or upstream business error, -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new task in your Asana.

Workflow Overview

We will build a simple workflow consisting of Start -> Asana: Create a Task -> Answer. When the workflow runs, it will create a new task under the specified project.

Step-by-Step Guide

1. Add Tool Node
   • In the workflow canvas, click the "+" button to add a new node.
   • Select the "Tools" tab in the pop-up panel.
   • Find and select Asana in the tools list.
   • In the Asana supported operations list, click to select Create a Task, which will add a corresponding node to the canvas.
2. Configure Node
   • Click the newly added Create a Task node, and the configuration panel for this node will expand on the right side.
   • Credentials Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select your configured Asana credentials.
   • Parameter Filling: Fill in the required parameters for creating a task in detail.
   • TagName: Enter the title of the task you wish to create, for example, "Complete Q1 Marketing Report".
   • WorkspaceGid: Enter the GID of the workspace where the task belongs. You can obtain this ID by running the Get Many Workspaces operation.
   • ProjectGids (Optional): If you want to add this task to one or more projects, provide a list of project GIDs. You can obtain these IDs by running the Get Many Projects operation.
3. Run and Verify
   • When all required parameters are filled in correctly, the error message in the upper right corner of the workflow canvas will disappear.
   • Click the "Test Run" button in the upper right corner of the canvas to execute the workflow.
   • After successful execution, you can click the log icon in the upper right corner to view the detailed input and output of the node. The Task object in the output will contain the details of the newly created task, including its GID. You can also log in to the Asana web application to check if the task was successfully created.

Final Workflow Display

After completing the above steps, your entire workflow is configured. Each time you run this workflow, a new task will be automatically created in your specified Asana workspace or project.

6. FAQs

Q: Why am I receiving a 401 Unauthorized or 403 Forbidden error?

A: This is usually related to your credentials. Please check the following:

• Whether the Personal Access Token configured in GoInsight is correct and not expired.
• Whether the token has permission to access the workspace, project, or task specified in the node parameters.
• Ensure that the token's permission scopes are sufficient to perform the operation you are attempting.

Q: How do I find the GID of a Workspace, Project, Task, or User?

A: GID is the unique identifier for resources in Asana. You can obtain it by:

• Through the Asana web application: When you view a project or task in your browser, its GID usually appears at the end of the URL.
• Through GoInsight nodes: You can use Get or Get Many operations in this tool to obtain GIDs. For example, first run Get Many Workspaces to get the workspace GID, then use it as input to Get Many Projects to get a list of project GIDs.

Q: I tried to create a task, but the operation failed. What should I check?

A: Please confirm the following common issues:

• Required Fields: Ensure that both required fields, TagName and WorkspaceGid, are filled in correctly.
• GID Validity: Check whether the WorkspaceGid or ProjectGids values you provided are valid GIDs that you have access to. An invalid or incorrect GID will cause the request to fail.

7. Official Documentation

For more detailed information about the Asana API, please refer to the official documentation:

Asana Official API Documentation