Asana Python Client Library

5.2.4 · active · verified Thu Apr 09

The official Python client library for interacting with the Asana API. It provides a simple interface to access Asana resources like tasks, projects, users, and workspaces. The current version is 5.2.4, and the library receives frequent updates, typically focusing on adding support for new API endpoints.

Warnings

breaking Major API changes in v4.0.0 altered client instantiation and resource method names. Older versions (pre-v4) used different patterns like `client.Client(api_key='...')` and resource methods such as `find_all` or `find_by_id`.
Fix: Update client instantiation to `asana.Client.access_token('YOUR_PAT')` or `asana.Client.oauth(...)`. Replace old resource methods (`projects.find_all`) with their v4+ equivalents (`projects.get_projects`). Consult the official v4 migration guide if available, or the current documentation.
gotcha Many collection-fetching methods (e.g., `get_tasks`, `get_projects`) return an `asana.Collection` object. This object is an iterator and does not immediately contain all results. To retrieve all items, you must iterate over it or explicitly request all results.
Fix: To iterate through results: `for item in client.tasks.get_tasks(...)`. To get all results as a list (for smaller collections, use with caution for large ones): `list(client.tasks.get_tasks(...))` or pass `iterator_type=None` to the method, e.g., `client.tasks.get_tasks(workspace_gid, iterator_type=None)`.
gotcha Asana API responses can be verbose. To optimize performance and reduce data transfer, always use the `opt_fields` parameter to specify only the fields you need in the response.
Fix: When calling any `get_` method for resources, pass a list of desired fields to `opt_fields`. Example: `task = client.tasks.get_task(task_gid, opt_fields=['name', 'notes', 'assignee.name'])`. This also applies to collection fetching methods.

Install

pip install asana Install stable version

Imports

Client
```
import asana
client = asana.Client.access_token('YOUR_PAT')
```
The Client constructor is commonly accessed via class methods like `access_token` or `oauth`.

Quickstart

This quickstart demonstrates how to initialize the Asana client using a Personal Access Token (PAT) and fetch the current user's details and a list of accessible workspaces. It handles token retrieval from environment variables for security and includes basic error handling.

import asana
import os

# Get your Personal Access Token from environment variable for security
personal_access_token = os.environ.get('ASANA_ACCESS_TOKEN', 'YOUR_ASANA_PAT')

if not personal_access_token or personal_access_token == 'YOUR_ASANA_PAT':
    print("Please set the ASANA_ACCESS_TOKEN environment variable or replace 'YOUR_ASANA_PAT' with your token.")
else:
    try:
        # Construct an Asana client
        client = asana.Client.access_token(personal_access_token)
        
        # Get information about the current user ('me')
        me = client.users.get_user('me')
        print(f"Connected as: {me['name']} (ID: {me['gid']})")
        
        # List workspaces accessible by the user
        workspaces = client.workspaces.get_workspaces(iterator_type=None) # iterator_type=None to get all results directly
        print("Workspaces:")
        for ws in workspaces:
            print(f"- {ws['name']} (ID: {ws['gid']})")
            
    except asana.error.NoAuthorizationError:
        print("Error: Invalid or expired Asana Personal Access Token.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →