Stories

A story represents an activity associated with an object in the Asana system. Stories are generated by the system whenever users take actions such as creating or assigning tasks, or moving tasks between projects. "Comments" are also a form of user-generated story.

See our forum post for more info on when conditional fields are returned.

StoryCompact

A Compact object reflects the default fields returned after a successful API request. See input/output options to include more fields in the response.

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
created_atstring(date-time)The time at which this resource was created.
created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
created_by.gidstringGlobally unique identifier of the resource, as a string.
created_by.resource_typestringThe base type of this resource.
created_by.namestringRead-only except when same user as requester. The user’s name.
resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
textstringCreate-only. Human-readable text for the story or comment.
This will not include the name of the creator.

Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say “assigned to …” as the text for a story can both be edited and change based on the language settings of the user making the request.

Use the resource_subtype property to discover the action that created the story.
{
  "gid": "12345",
  "resource_type": "story",
  "created_at": "2012-02-22T02:06:58.147Z",
  "created_by": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  },
  "resource_subtype": "comment_added",
  "text": "marked today"
}

Story

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
created_atstring(date-time)The time at which this resource was created.
html_textstringOpt in. HTML formatted text for a comment. This will not include the name of the creator.
is_pinnedbooleanConditional. Whether the story should be pinned on the resource.
resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
sticker_namestringThe name of the sticker in this story. null if there is no sticker.
textstringThe plain text of the comment to add. Cannot be used with html_text.
assigneeobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
assignee.gidstringGlobally unique identifier of the resource, as a string.
assignee.resource_typestringThe base type of this resource.
assignee.namestringRead-only except when same user as requester. The user’s name.
created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
created_by.gidstringGlobally unique identifier of the resource, as a string.
created_by.resource_typestringThe base type of this resource.
created_by.namestringRead-only except when same user as requester. The user’s name.
custom_fieldobjectCustom fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the custom fields developer documentation for more information about how custom fields relate to various resources in Asana.

Users in Asana can lock custom fields, which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code 403 Forbidden.
custom_field.gidstringGlobally unique identifier of the resource, as a string.
custom_field.resource_typestringThe base type of this resource.
custom_field.date_valueobjectConditional. Only relevant for custom fields of type date. This object reflects the chosen date (and optionally, time) value of a date custom field. If no date is selected, the value of date_value will be null.
custom_field.date_value.datestringA string representing the date in YYYY-MM-DD format.
custom_field.date_value.date_timestringA string representing the date in ISO 8601 format. If no time value is selected, the value of date-time will be null.
custom_field.display_valuestring¦nullA string representation for the value of the custom field. Integrations that don't require the underlying type should use this field to read values. Using this field will future-proof an app against new custom field types.
custom_field.enabled`booleanConditional. Determines if the custom field is enabled or not.
custom_field.enum_options[object]Conditional. Only relevant for custom fields of type enum. This array specifies the possible values which an enum custom field can adopt. To modify the enum options, refer to working with enum options.
» {}. gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.colorstringThe color of the enum option. Defaults to none.
» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.namestringThe name of the enum option.
custom_field.enum_valueobjectConditional. Only relevant for custom fields of type enum. This object is the chosen value of an enum custom field.
custom_field.enum_value.gidstringGlobally unique identifier of the resource, as a string.
custom_field.enum_value.resource_typestringThe base type of this resource.
custom_field.enum_value.colorstringThe color of the enum option. Defaults to none.
custom_field.enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
custom_field.enum_value.namestringThe name of the enum option.
custom_field.multi_enum_values[object]Conditional. Only relevant for custom fields of type multi_enum. This object is the chosen values of a multi_enum custom field.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.colorstringThe color of the enum option. Defaults to none.
» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.namestringThe name of the enum option.
custom_field.namestringThe name of the custom field.
custom_field.number_valuenumberConditional. This number is the value of a number custom field.
custom_field.resource_subtypestringThe type of the custom field. Must be one of the given values.
custom_field.text_valuestringConditional. This string is the value of a text custom field.
custom_field.typestringDeprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values.
dependencyobjectThe task is the basic object around which many operations in Asana are centered.
dependency.gidstringGlobally unique identifier of the resource, as a string.
dependency.resource_typestringThe base type of this resource.
dependency.namestringThe name of the task.
dependency.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource subtype milestone represent a single moment in time. This means tasks with this subtype cannot have a start_date.
duplicate_ofobjectThe task is the basic object around which many operations in Asana are centered.
duplicate_of.gidstringGlobally unique identifier of the resource, as a string.
duplicate_of.resource_typestringThe base type of this resource.
duplicate_of.namestringThe name of the task.
duplicate_of.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource subtype milestone represent a single moment in time. This means tasks with this subtype cannot have a start_date.
duplicated_fromobjectThe task is the basic object around which many operations in Asana are centered.
duplicated_from.gidstringGlobally unique identifier of the resource, as a string.
duplicated_from.resource_typestringThe base type of this resource.
duplicated_from.namestringThe name of the task.
duplicated_from.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource subtype milestone represent a single moment in time. This means tasks with this subtype cannot have a start_date.
followerobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
follower.gidstringGlobally unique identifier of the resource, as a string.
follower.resource_typestringThe base type of this resource.
follower.namestringRead-only except when same user as requester. The user’s name.
heartedbooleanDeprecated - please use likes instead.

Conditional. True if the story is hearted by the authorized user, false if not.
heartsobjectDeprecated - please use likes instead.

Conditional. Array of likes for users who have hearted this story.
gidstringGlobally unique identifier of the object, as a string.
userobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
user.gidstringGlobally unique identifier of the resource, as a string.
user.resource_typestringThe base type of this resource.
user.namestringRead-only except when same user as requester. The user’s name.
is_editablebooleanConditional. Whether the text of the story can be edited after creation.
is_editedbooleanConditional. Whether the text of the story has been edited after creation.
likedbooleanConditional. True if the story is liked by the authorized user, false if not.
likes[object]Conditional. Array of likes for users who have liked this story.
» {}.gidstringGlobally unique identifier of the object, as a string.
» {}.userobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
» {}.user.gidstringGlobally unique identifier of the resource, as a string.
» {}.user.resource_typestringThe base type of this resource.
» {}.user.namestringRead-only except when same user as requester. The user’s name.
new_approval_statusstringConditional. The new value of approval status.
new_date_valueobjectConditional The new value of a date custom field story.
new_date_value.due_atstring(date-time)¦nullThe UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with due_on.
new_date_value.due_onstring(date)The localized day on which this goal is due. This takes a date with format YYYY-MM-DD.
new_date_value.start_onstring(date)¦nullThe day on which work for this goal begins, or null if the goal has no start date. This takes a date with YYYY-MM-DD format, and cannot be set unless there is an accompanying due date.
new_datesobjectConditional.
new_dates.due_atstring(date-time)¦nullThe UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with due_on.
new_dates.due_onstring(date)The localized day on which this goal is due. This takes a date with format YYYY-MM-DD.
new_dates.start_onstring(date)¦nullThe day on which work for this goal begins, or null if the goal has no start date. This takes a date with YYYY-MM-DD format, and cannot be set unless there is an accompanying due date.
new_enum_valueobjectEnum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.

You can add enum options to a custom field by using the POST /custom_fields/custom_field_gid/enum_options endpoint.

It is not possible to remove or delete an enum option. Instead,
enum options can be disabled by updating the enabled field to false with the PUT /enum_options/enum_option_gid endpoint. Other attributes can be updated similarly.

On creation of an enum option, enabled is always set to true,
meaning the enum option is a selectable value for the custom field. Setting enabled=false is equivalent to “trashing” the enum option in the Asana web app within the “Edit Fields” dialog. The enum option will no longer be selectable but, if the enum option value was
previously set within a task, the task will retain the value.


Enum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using insert_before or insert_after to reference an existing enum option. Only one of insert_before and insert_after can be provided when creating a new enum option.


An enum options list can be reordered with the POST /custom_fields/custom_field_gid/enum_options/insert endpoint.
new_enum_value.gidstringGlobally unique identifier of the resource, as a string.
new_enum_value.resource_typestringThe base type of this resource.
new_enum_value.colorstringThe color of the enum option. Defaults to none.
new_enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
new_enum_value.namestringThe name of the enum option.
new_multi_enum_values[object]Conditional. The new value of a multi_enum custom field story.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.colorstringThe color of the enum option. Defaults to none.
» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.namestringThe name of the enum option.
new_namestringConditional.
new_number_valueintegerConditional.
new_people_value[object]Conditional. The new value of a people custom field story.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.namestringRead-only except when same user as requester. The user’s name.
new_resource_subtypestringConditional.
new_sectionobjectA section is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.
new_section.gidstringGlobally unique identifier of the resource, as a string.
new_section.resource_typestringThe base type of this resource.
new_section.namestringThe name of the section (i.e. the text displayed as the section header).
new_text_valuestringConditional.
num_heartsintegerDeprecated - please use likes instead.

Conditional. The number of users who have hearted this story.
num_likesintegerConditional. The number of users who have liked this story.
old_approval_statusstringConditional. The old value of approval status.
old_date_valueobjectConditional. The old value of a date custom field story.
old_date_value.due_atstring(date-time)¦nullThe UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with due_on.
old_date_value.due_onstring(date)The localized day on which this goal is due. This takes a date with format YYYY-MM-DD.
old_date_value.start_onstring(date)¦nullThe day on which work for this goal begins, or null if the goal has no start date. This takes a date with YYYY-MM-DD format, and cannot be set unless there is an accompanying due date.
old_datesobjectConditional.
old_dates.due_atstring(date-time)¦nullThe UTC date and time on which this task is due, or null if the task has no due time. This takes an ISO 8601 date string in UTC and should not be used together with due_on.
old_dates.due_onstring(date)The localized day on which this goal is due. This takes a date with format YYYY-MM-DD.
old_dates.start_onstring(date)¦nullThe day on which work for this goal begins, or null if the goal has no start date. This takes a date with YYYY-MM-DD format, and cannot be set unless there is an accompanying due date.
old_enum_valueobjectEnum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 500.

You can add enum options to a custom field by using the POST /custom_fields/custom_field_gid/enum_options endpoint.

It is not possible to remove or delete an enum option. Instead,
enum options can be disabled by updating the enabled field to false with the PUT /enum_options/enum_option_gid endpoint. Other attributes can be updated similarly.

On creation of an enum option, enabled is always set to true,
meaning the enum option is a selectable value for the custom field. Setting enabled=false is equivalent to “trashing” the enum option in the Asana web app within the “Edit Fields” dialog. The enum option will no longer be selectable but, if the enum option value was
previously set within a task, the task will retain the value.


Enum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using insert_before or insert_after to reference an existing enum option. Only one of insert_before and insert_after can be provided when creating a new enum option.


An enum options list can be reordered with the POST /custom_fields/custom_field_gid/enum_options/insert endpoint.
old_enum_value.gidstringGlobally unique identifier of the resource, as a string.
old_enum_value.resource_typestringThe base type of this resource.
old_enum_value.colorstringThe color of the enum option. Defaults to none.
old_enum_value.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
old_enum_value.namestringThe name of the enum option.
old_multi_enum_values[object]Conditional. The old value of a multi-enum custom field story.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.colorstringThe color of the enum option. Defaults to none.
» {}.enabledbooleanWhether or not the enum option is a selectable value for the custom field.
» {}.namestringThe name of the enum option.
old_namestringConditional.
old_number_valueintegerConditional
old_people_value[object]Conditional. The old value of a people custom field story.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.namestringRead-only except when same user as requester. The user’s name.
old_resource_subtypestringConditional.
old_sectionobjectA section is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.
old_section.gidstringGlobally unique identifier of the resource, as a string.
old_section.resource_typestringThe base type of this resource.
old_section.namestringThe name of the section (i.e. the text displayed as the section header).
old_text_valuestringConditional.
previews[object]Conditional. A collection of previews to be displayed in the story.

Note: This property only exists for comment stories.
» {}.fallbackstringSome fallback text to display if unable to display the full preview.
» {}.footerstringText to display in the footer.
» {}.headerstringText to display in the header.
» {}.header_linkstringWhere the header will link to.
» {}.html_textstringHTML formatted text for the body of the preview.
» {}.textstringText for the body of the preview.
» {}.titlestringText to display as the title.
» {}.title_linkstringWhere to title will link to.
projectobjectA project represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.
project.gidstringGlobally unique identifier of the resource, as a string.
project.resource_typestringThe base type of this resource.
project.namestringName of the project. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
sourcestringThe component of the Asana product the user used to trigger the story.
storyobjectA story represents an activity associated with an object in the Asana system.
story.gidstringGlobally unique identifier of the resource, as a string.
story.resource_typestringThe base type of this resource.
story.created_atstring(date-time)The time at which this resource was created.
story.created_byobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
story.created_by.gidstringGlobally unique identifier of the resource, as a string.
story.created_by.resource_typestringThe base type of this resource.
story.created_by.namestringRead-only except when same user as requester. The user’s name.
story.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
story.textstringCreate-only. Human-readable text for the story or comment.
This will not include the name of the creator.

Note: This is not guaranteed to be stable for a given type of story. For example, text for a reassignment may not always say “assigned to …” as the text for a story can both be edited and change based on the language settings of the user making the request.

Use the resource_subtype property to discover the action that created the story.
tagobjectA tag is a label that can be attached to any task in Asana. It exists in a single workspace or organization.
tag.gidstringGlobally unique identifier of the resource, as a string.
tag.resource_typestringThe base type of this resource.
tag.namestringName of the tag. This is generally a short sentence fragment that fits on a line in the UI for maximum readability. However, it can be longer.
targetobjectThe object this story is associated with. Currently may only be a task.
target.gidstringGlobally unique identifier of the resource, as a string.
target.resource_typestringThe base type of this resource.
target.namestringThe name of the task.
target.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource subtype milestone represent a single moment in time. This means tasks with this subtype cannot have a start_date.
taskobjectThe task is the basic object around which many operations in Asana are centered.
task.gidstringGlobally unique identifier of the resource, as a string.
task.resource_typestringThe base type of this resource.
task.namestringThe name of the task.
task.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource subtype milestone represent a single moment in time. This means tasks with this subtype cannot have a start_date.
typestringnone
{
  "gid": "12345",
  "resource_type": "story",
  "created_at": "2012-02-22T02:06:58.147Z",
  "html_text": "<body>This is a comment.</body>",
  "is_pinned": false,
  "resource_subtype": "comment_added",
  "sticker_name": "dancing_unicorn",
  "text": "This is a comment.",
  "assignee": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  },
  "created_by": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  },
  "custom_field": {
    "gid": "12345",
    "resource_type": "custom_field",
    "date_value": {
      "date": "2024-08-23",
      "date_time": "2024-08-23T22:00:00.000Z"
    },
    "display_value": "blue",
    "enabled": true,
    "enum_options": [
      {
        "gid": "12345",
        "resource_type": "enum_option",
        "color": "blue",
        "enabled": true,
        "name": "Low"
      }
    ],
    "enum_value": {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    },
    "multi_enum_values": [
      {
        "gid": "12345",
        "resource_type": "enum_option",
        "color": "blue",
        "enabled": true,
        "name": "Low"
      }
    ],
    "name": "Status",
    "number_value": 5.2,
    "resource_subtype": "text",
    "text_value": "Some Value",
    "type": "text"
  },
  "dependency": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Bug Task",
    "resource_subtype": "default_task"
  },
  "duplicate_of": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Bug Task",
    "resource_subtype": "default_task"
  },
  "duplicated_from": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Bug Task",
    "resource_subtype": "default_task"
  },
  "follower": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  },
  "hearted": false,
  "hearts": [
    {
      "gid": "12345",
      "user": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    }
  ],
  "is_editable": false,
  "is_edited": false,
  "liked": false,
  "likes": [
    {
      "gid": "12345",
      "user": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    }
  ],
  "new_approval_status": "approved",
  "new_date_value": {
    "due_at": "2019-09-15T02:06:58.158Z",
    "due_on": "2019-09-15",
    "start_on": "2019-09-14"
  },
  "new_dates": {
    "due_at": "2019-09-15T02:06:58.158Z",
    "due_on": "2019-09-15",
    "start_on": "2019-09-14"
  },
  "new_enum_value": {
    "gid": "12345",
    "resource_type": "enum_option",
    "color": "blue",
    "enabled": true,
    "name": "Low"
  },
  "new_multi_enum_values": [
    {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    }
  ],
  "new_name": "This is the New Name",
  "new_number_value": 2,
  "new_people_value": [
    {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    }
  ],
  "new_resource_subtype": "milestone",
  "new_section": {
    "gid": "12345",
    "resource_type": "section",
    "name": "Next Actions"
  },
  "new_text_value": "This is the New Text",
  "num_hearts": 5,
  "num_likes": 5,
  "old_approval_status": "pending",
  "old_date_value": {
    "due_at": "2019-09-15T02:06:58.158Z",
    "due_on": "2019-09-15",
    "start_on": "2019-09-14"
  },
  "old_dates": {
    "due_at": "2019-09-15T02:06:58.158Z",
    "due_on": "2019-09-15",
    "start_on": "2019-09-14"
  },
  "old_enum_value": {
    "gid": "12345",
    "resource_type": "enum_option",
    "color": "blue",
    "enabled": true,
    "name": "Low"
  },
  "old_multi_enum_values": [
    {
      "gid": "12345",
      "resource_type": "enum_option",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    }
  ],
  "old_name": "This was the Old Name",
  "old_number_value": 1,
  "old_people_value": [
    {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    }
  ],
  "old_resource_subtype": "default_task",
  "old_section": {
    "gid": "12345",
    "resource_type": "section",
    "name": "Next Actions"
  },
  "old_text_value": "This was the Old Text",
  "previews": [
    {
      "fallback": "Greg: Great! I like this idea.\\n\\nhttps//a_company.slack.com/archives/ABCDEFG/12345678",
      "footer": "Mar 17, 2019 1:25 PM",
      "header": "Asana for Slack",
      "header_link": "https://asana.comn/apps/slack",
      "html_text": "<body>Great! I like this idea.</body>",
      "text": "Great! I like this idea.",
      "title": "Greg",
      "title_link": "https://asana.slack.com/archives/ABCDEFG/12345678"
    }
  ],
  "project": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy"
  },
  "source": "web",
  "story": {
    "gid": "12345",
    "resource_type": "story",
    "created_at": "2012-02-22T02:06:58.147Z",
    "created_by": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "resource_subtype": "comment_added",
    "text": "marked today"
  },
  "tag": {
    "gid": "12345",
    "resource_type": "tag",
    "name": "Stuff to buy"
  },
  "target": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Bug Task",
    "resource_subtype": "default_task"
  },
  "task": {
    "gid": "12345",
    "resource_type": "task",
    "name": "Bug Task",
    "resource_subtype": "default_task"
  },
  "type": "comment"
}