Will Asana deprecate the opt_expand option for API call

I use the opt_expand feature on many of the API calls made to Asana. My application currently relies heavily on it. But this option does have much documentation if any. Does Asana foresee any need to deprecate this option in the future, if so what are the alternatives?

Please read this before posting

  • If you received an error from the API that you’re looking for help with, please include the error in your post and be descriptive of the requests you made that received the errors. To be clear, we need the error in the JSON response from the API, not the error your code raised.
  • Do not share any API credentials. Please check that the code you’re pasting into the post does not contain any real OAuth tokens or personal access tokens. If you have exposed credentials, you should revoke them immediately.
1 Like

I don’t think there is a need for more documentation, it just allows you to query entire sub objects. Just be careful: the more you ask for, and the more expensive your request becomes, as a result you’ll be reaching rate limit quicker. You could replace expand and cherry pick what you need like the id and the name of a parent task for example.

@Phil_Seeman can you confirm what I am saying please?

@Ziara_Diaz is correct that opt_expand is deprecated and Asana does not want people to be using it. So they purposely removed it from the documentation some time ago.

That being said, it does still work. @Ziara_Diaz, I was told that it would never be removed and rendered non-functional.

However, “never” is a long time! So it doesn’t hurt to check again as you’re doing.

@AndrewWong @Kem_Ozbek are you able to comment on this matter? Thanks for any info!

1 Like

Good to know! They why not use opt_fields and simply list what you need @Ziara_Diaz ? It would be good to limit the scope of what ask, regarding rate limits.

1 Like

opt_fields does not work with getting the attributes from a task. For example this API call:

  let tasks    = await cleint.tasks.findAll({
    project: '123',
    opt_expand: [
     'assignee' //The assignee of the task
      'memberships', // List of projects task belongs to
      'custom_fields', // List of custom fields with values
      'created_at', // When task was created
      'name', // Task's title
      'parent' // Parent task ID (if subtask)

The opt_fields alternative to opt_expand is to use dot notation; for example opt_fields=assignee.name, assignee.ID

Although in your example, that would be a whole lot of fields and dots!

1 Like

Hi @Ziara_Diaz ,

As Bastien and Phil have already mentioned, we have deprecated opt_expand as it is an expensive request and we want to discourage apps from requesting all fields by default. The alternative is to use opt_fields and use dot notation to request for the data you need. You can read more about opt_fields here in our documentation.

Additionally, instead of using findAll to get tasks please use getTasks (See sample node code in → Docs).

For reference here are fields that you can specify in the opt_fields for tasks.

Here is an example usage:

// Tested on node-asana: v0.18.13
const asana = require("asana");

const client = asana.Client.create().useAccessToken(

async function printAsanaTasks() {
  let tasks = await client.tasks.getTasks({
    project: "<YOUR_PROJECT_GID>",
    opt_fields: [

  // Pretty print tasks
  console.log(JSON.stringify(tasks["data"], null, 2));


1 Like