FAQ

This page covers some of the most frequently asked questions when working with the Asana API (for a list of FAQs about the general Asana product, see Frequently Asked Questions).

If you have a question that is not covered and/or would make a great addition to this FAQ page, feel free to leave your feedback by completing this form!

Introduction

What do Asana customers use the API for?

Asana customers use the API to:

• Integrate or sync Asana with the other tools they use
• Create custom reports and draw insights from their Asana data
• Automate repetitive processes or create custom workflows
• Extend and customize Asana’s native features
• Programmatically manage accounts at scale

For more examples, see common use cases.

How do I set up my developer environment?

Before moving forward with making sample API requests or building apps that leverage that Asana API, we recommend first getting an Asana developer sandbox. A developer sandbox is a temporary Asana domain with limited users.

Additionally, you can always use the existing workspace you've created (or joined) to create your app and generate a personal access token to make requests against the API. Note that by making API requests against data in your workspace, you will be operating on real data in that workspace.

What apps or tools have others built?

Asana integrates with dozens of top tools and apps, which you can browse in our app directory. See examples and get inspired!

Getting started

What does GID mean?

This stands for "global ID." In Asana, IDs are globally unique, across all workspaces and even across all data types.

What is my workspace's GID?

When making API requests to some API endpoints (e.g., search tasks in a workspace), you'll need to provide your workspace GID. You can get all your accessible workspace IDs by first logging in to Asana in your browser, then visiting https://app.asana.com/api/1.0/workspaces.

Under the hood, your browser is making a GET request to an API endpoint that retrieves all workspaces visible to the authorized user.

What is my user GID?

You can get your user GID by first logging in to Asana in your browser, then visiting https://app.asana.com/api/1.0/users/me.

Under the hood, your browser is making a GET request to an API endpoint that retrieves metadata about the logged-in user.

What tools can I use to make API requests?

In addition to making basic requests in your terminal via cURL, Asana also offers many other ways to make API requests:

API explorer

Asana's REST API reference allows you to explore different REST API endpoints through an in-context, easy-to-use interface. Using this built-in API explorer, you can make API requests (and view responses) directly in your browser.

For more details, see the documentation for the API explorer.

Postman Collection

If you prefer a convenient way to make requests on your local machine (i.e., instead of in your browser) with an interactive UI, we recommend using Postman. As an added benefit, using Postman allows you to save past configurations, requests, and responses -- making it easy to revisit or re-request previous HTTP calls.

Visit the Postman Collection documentation to get started.

Client libraries

Asana offers official client libraries in several popular coding languages. Visit the client libraries documentation to get started.

Is Asana down?

We work hard to ensure a functional environment for users and developers. You can follow our status page for the latest reported updates. Additionally, you can get this information via an RSS feed.

Navigating the API

Where can I see schemas for objects available in the API?

To see object schemas directly in the API explorer, select the 200 response for a GET request for that object. For example, see the 200 response option here (highlighted in red) for GET /users/{user_gid}:

In the above example, selecting 200 will open a modal that features the full schema for that object (in this case, a user object).

Object schemas (i.e., data models) can also be found by selecting the object in the sidebar (e.g., Attachments) of the API reference.

Where can I view example responses for an API request?

To view example responses for any given API endpoint, select an HTTP response code in the RESPONSE section of the endpoint page in the API reference. Using the GET /project/{project_gid} endpoint as an example, here is the RESPONSE section highlighted in red:

By selecting an HTTP response code (e.g., 200), you'll see an example of the full JSON response output:

Why do some API responses contain limited fields? What is a "compact" response?

Some requests return "compact" representations of objects in order to conserve resources and complete the request more efficiently (e.g., GET /tasks returns compact task objects).

Other times, requests return more information (i.e., fields) than you may need (e.g., GET /tasks/{task_gid} returns the full/complete task).

Using input/output options allows you to list the exact set of fields that the API should return for the objects.

Which opt_fields are available in my API request?

If opt_fields are available for an API request, you can check which valid fields can be included in that request by visiting the response object's schema page in the API reference (e.g., the full schema for tasks).

Alternatively, while viewing an endpoint (e.g., GET /goals) in the API reference, you may also review the enumerated values listed in the opt_fields section.

Let’s look at an example of including opt_fields to get more data.

In the above example, enumerated values such as liked, status, is_workspace_level, etc. can be included as opt_fields values in the request, allowing you to customize the response you receive from the API.

Authentication

Do I need an API key? How do I authenticate with the Asana API?

The easiest way to get started is to created a personal access token (which is like a traditional "API key" for your user). Beyond that, there are several options for authenticating, such as a service account and OAuth (including OpenID Connect). The purpose of your app, who uses it, and its features will dictate the method of auth that’s best for your app. To the various authentication options and why you might want to use each of them, see Authentication.

How do I use Excel and VBA (Visual Basic for Applications) to make authenticated requests?

See this post in the developer forum.

Errors

Are there API limits that I should be aware of?

See the rate limits documentation for details.

Why do I see an Invalid JSON error message when making a POST request?

The Asana API accepts JSON or form-encoded content in requests and returns JSON content in all of its responses, including errors. If the API sees that no form fields are present, it attempts to look for a JSON body. Malformed or empty bodies are invalid JSON, so you may want to review your JSON content.

To view example JSON request bodies, feel free to build dynamic requests through the API explorer in our API reference. cURL requests will automatically build in the right-side panel as you provide values to input fields.

I'm getting an error that says The result is too large. You should use pagination. How do I proceed?

For requests that will return large result sets, the API may truncate the result or timeout while attempting to gather the data. Pagination ensures a more reliable experience by limiting requests to a smaller number of objects at a time (i.e., up to 100 per "page" of results), ultimately getting you the results faster. Should there be more results, the API will return an offset that will allow you to access the next page. See pagination for further details on implementation.

Tasks

How do I create / read / update / delete a task through the API?

Visit the quick start guide to see how you can perform CRUD (i.e., create, read, update, delete) operations on a task. These same operations that you performed on a task through the API can be applied to many other objects in your Asana instance as well (e.g., projects, portfolios, etc.).

How do I get all tasks in a project along with their section?

This particular request refers to a query for all tasks in a project, with each task including a reference of not only the project, but also the section that the task belongs to.

This information is found in the memberships array of a task (see the task schema). To form the request, make a GET /projects/{project_gid}/tasks call using special selectors for nested fields. Using your own details for PROJECT_GID and PERSONAL_ACCESS_TOKEN below, your request may look like:

curl --location --request GET 'https://app.asana.com/api/1.0/projects/PROJECT_GID/tasks?opt_fields=memberships.(project|section).name' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer PERSONAL_ACCESS_TOKEN'

How do I get all tasks assigned to me?

This involves making a request to GET /tasks with specific query parameters:

curl --location --request GET 'https://app.asana.com/api/1.0/tasks?assignee=me&workspace=WORKSPACE_GID&completed_since=now&limit=10' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer PERSONAL_ACCESS_TOKEN'

In the above example, we make the request by passing:

• assignee=me to get the tasks assigned to you
• workspace=WORKSPACE_GID because the request requires one of workspace, project, tag, or section, and you want all your tasks in the whole workspace
• completed_since=now which means "all tasks completed after now" (i.e., all your incomplete tasks). If you want all tasks ever assigned to you, including completed tasks, you can omit this parameter
• limit=10 which means "return the first 10 results" for pagination

Projects

What is the GID of the "My Tasks" project?

My Tasks is a list of all the tasks assigned to you in a given organization or workspace. To retrieve the GID of the authenticated user's task list, make a request to the GET /users/{user_gid}/user_task_list endpoint, which provides direct API access to the user's "My Tasks" view in Asana.

Webhooks

📘

Webhooks guide

For a comprehensive guide on implementing webhooks, visit the webhooks guide.

What are the limits for webhooks?

See the limits section of the webhooks guide for details.

Why have I stopped receiving events?

This can happen when your registered webhook endpoint ignores incoming heartbeat events. We send periodic heartbeat events to your webhook endpoint every 8 hours to keep track of the last time that delivery succeeded. If we receive no response to heartbeat events after 24 hours, we will delete the registered webhook connection.

To fix this, you will need to modify your webhook endpoint code to respond to heartbeat events and re-establish a webhook connection.

Why does my computed webhook signature differ from X-Hook-Signature?

When computing your SHA256 HMAC signature, make sure to utilize the X-Hook-Secret and the full body of the request. The X-Hook-Secret can be found in the header of the initial request sent to your webhook endpoint during the initial handshake process. The full body of the request should also be used, not just a portion of the data inside the request body.

Additionally, check the documentation of the library you are using to compute the SHA256 HMAC signature, as it may require you to convert the request body from an object into a string.

Custom fields

📘

Custom fields guide

For a comprehensive guide on working with custom fields through the API, visit the custom fields guide. If you'd like a introductory overview of how custom fields can be used in the Asana product, visit the product guide.

How do I create / update a task with specific values for custom fields?

As an example, let's say you want to create a task in a particular project, and that project includes two custom fields: a text custom field (i.e., "resource_subtype": "text"), and an enum custom field (i.e., "resource_subtype": "enum").

To create the task with values for these two custom fields, you should first make a request to GET /projects/{project_gid}/custom_field_settings, which returns a (compact) list of all of the custom fields settings on a project. Note the GID values of these custom field settings in your project, as well as the GID values of the individual enum options available.

Once that is done, you can make a request to POST /tasks, providing the GIDs of the custom fields from above, along with your intended values for these custom fields. Here's an example of such a request:

curl --request POST \
     --url 'https://app.asana.com/api/1.0/tasks' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer PERSONAL_ACCESS_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "custom_fields": {
      "TEXT_CUSTOM_FIELD_GID": "Sample value for a custom field of type text",
      "ENUM_CUSTOM_FIELD_GID": "ENUM_OPTION_GID"
    },
    "projects": [
      "PROJECT_GID"
    ],
    "name": "Sample task name"
  }
}
'

Note that while a direct text value (as a string) can be provided for text custom fields, the value for an enum custom field must be the GID of the enum option itself and not the text name of the enum option (e.g., the correct value is "1234567890", not "Option 1").

A similar process applies to updating a task as well.

App components

📘

App components guide

For a comprehensive guide on working with custom fields through the API, visit the app components guide.

I'm getting an error saying "Something went wrong. Try again later."

This typically happens when we receive a response from the app server that we do not understand. To ensure that Asana is able to read the response from the app server, check that the app server is returning the required properties listed in the corresponding schema of the endpoint being called (see the app component schema, e.g., widget). Additionally, for certain properties like color and width, check that the value the app server is returning is a valid option under the Enumerated Values dropdown of an app component schema. The easiest way to build for app components in a dynamic, interactive test environment is to use the UI builder.

Another reason that you may be seeing this message is when your app server is not using CORS. In order to update the Asana user interface (e.g., populating a widget with external data), requests are made from the client to your app server. As such, enabling and configuring CORS is required. See security for more information.

My app server endpoints are not being triggered

Check that the endpoint paths saved for your app in the developer console match the endpoint paths that you created for your app server. For example, your app server's endpoint to GET form metadata might be https://app.example.com/form/metadata, while in your app's settings it is saved as https://app.example.com/metadata. Since these paths are non-matching, when Asana makes a request to GET form metadata, it will be making requests to https://app.example.com/metadata instead of https://app.example.com/form/metadata.

Additionally, some app server responses may contain an on_change_callback and an on_submit_callback property. Check that the endpoints provided for these values are what you expected.

I am unable to trigger the installation process again

In the event that you would like to trigger your app's installation again (e.g., for testing purposes), you can visit https://app.asana.com/-/install_platform_ui_app?app_id=<app_client_id>. You can find your app_client_id in the URL of your app in the developer console.

[Rule actions] My app server is not receiving a response back from Asana

The app server for rule action must be hosted in order for rule actions to function. For a brief list of popular hosting options, see hosting.

My app does not appear in the app gallery of my organization

Ensure that your app is added to your organization. This can be done in your app's setting in the developer console under Install your app > + Add organization.

[Python Flask] I can't add an action to a rule, even though the app is installed in a project

If you are trying to add an action to a rule and you see errors after a request is made to your action metadata endpoint, this may be related to security guidelines about CORS (i.e., adding cross-origin resource sharing headers to response).

Instructions on how to add CORS for Python Flask app server:

1. pip install Flask-Cors
2. Import Flask-CORS: from flask_cors import CORS
3. Add CORS(app) after app = Flask(**name**)

Additionally, for development, use https.

Instructions on how to add https to Python Flask app server (for development):

1. In your terminal window, run the following commands in the root directory of your Python Flask app server. This step is the same as the "Enable HTTPS" step on the app-components-example-app README.
2. Run openssl req -x509 -newkey rsa:2048 -keyout keytmp.pem -out cert.pem -days 365
3. Run openssl rsa -in keytmp.pem -out key.pem
4. If serving the application with python <APP_SERVER_NAME>.py command, add ssl_context=("cert.pem", "key.pem") to app.run. Otherwise, if the application is being served using the Flask command use flask run --cert=cert.pem --key=key.pem
5. After completing step 2, you should see something similar to the following in your command line Running on https://<HOST_NAME>:<PORT> (Press CTRL+C to quit)
6. If you are on Google Chrome navigate to your app server https://<HOST_NAME>:<PORT>/ in the URL you should see a warning "Your connection is not private", type "thisisunsafe" on your keyboard. Close the tab after you have done this. This is the same as the “If blocked by Chrome…” step on the app-components-example-app README
7. Remember to update rule action's "Run action URL" and "Form metadata URL" for your app in Asana’s developer console to use https://<HOST_NAME>:<PORT>/<YOUR_RULE_ACTION_RUN_ACTION_ENDPOINT> and https://<HOST_NAME>:<PORT>/<YOUR_RULE_ACTION_METADATA_ENDPOINT>

App management

Why can't a user / peer see my app in their workspace?

By default, apps are private to you. If your user/peer sees an error when trying to authorize, you may need to update your app sharing settings.

To share your app, visit the Manage Distribution section of the developer console and share your app with a specific workspace or with any workspace. Review the documentation for sharing your app for additional details.

Exporting data

How do I export portfolio data into a CSV or spreadsheet?

You can use the Portfolio to CSV Export script to extract project metadata from a nested portfolio structure in Asana. The resulting data, retrieved from requests to Asana's API, is formatted and exported in CSV format.