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.
Property | Type | Description |
---|---|---|
gid | string | Globally unique identifier of the resource, as a string. |
resource_type | string | The base type of this resource. |
created_at | string(date-time) | The time at which this resource was created. |
created_by | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
created_by .gid | string | Globally unique identifier of the resource, as a string. |
created_by .resource_type | string | The base type of this resource. |
created_by .name | string | Read-only except when same user as requester. The user’s name. |
resource_subtype | string | The 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. |
text | string | Create-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
Property | Type | Description |
---|---|---|
gid | string | Globally unique identifier of the resource, as a string. |
resource_type | string | The base type of this resource. |
created_at | string(date-time) | The time at which this resource was created. |
html_text | string | Opt in. HTML formatted text for a comment. This will not include the name of the creator. |
is_pinned | boolean | Conditional. Whether the story should be pinned on the resource. |
resource_subtype | string | The 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_name | string | The name of the sticker in this story. null if there is no sticker. |
text | string | The plain text of the comment to add. Cannot be used with html_text . |
assignee | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
assignee .gid | string | Globally unique identifier of the resource, as a string. |
assignee .resource_type | string | The base type of this resource. |
assignee .name | string | Read-only except when same user as requester. The user’s name. |
created_by | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
created_by .gid | string | Globally unique identifier of the resource, as a string. |
created_by .resource_type | string | The base type of this resource. |
created_by .name | string | Read-only except when same user as requester. The user’s name. |
custom_field | object | Custom 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 .gid | string | Globally unique identifier of the resource, as a string. |
custom_field .resource_type | string | The base type of this resource. |
custom_field .date_value | object | Conditional . 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 .date | string | A string representing the date in YYYY-MM-DD format. |
custom_field .date_value .date_time | string | A 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_value | string¦null | A 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` | boolean | Conditional. 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. |
» {} . gid | string | Globally unique identifier of the resource, as a string. |
» {} .resource_type | string | The base type of this resource. |
» {} .color | string | The color of the enum option. Defaults to none . |
» {} .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
» {} .name | string | The name of the enum option. |
custom_field .enum_value | object | Conditional. Only relevant for custom fields of type enum . This object is the chosen value of an enum custom field. |
custom_field .enum_value .gid | string | Globally unique identifier of the resource, as a string. |
custom_field .enum_value .resource_type | string | The base type of this resource. |
custom_field .enum_value .color | string | The color of the enum option. Defaults to none . |
custom_field .enum_value .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
custom_field .enum_value .name | string | The 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. |
» {} .gid | string | Globally unique identifier of the resource, as a string. |
» {} .resource_type | string | The base type of this resource. |
» {} .color | string | The color of the enum option. Defaults to none . |
» {} .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
» {} .name | string | The name of the enum option. |
custom_field .name | string | The name of the custom field. |
custom_field .number_value | number | Conditional. This number is the value of a number custom field. |
custom_field .resource_subtype | string | The type of the custom field. Must be one of the given values. |
custom_field .text_value | string | Conditional. This string is the value of a text custom field. |
custom_field .type | string | Deprecated: new integrations should prefer the resource_subtype field. The type of the custom field. Must be one of the given values. |
dependency | object | The task is the basic object around which many operations in Asana are centered. |
dependency .gid | string | Globally unique identifier of the resource, as a string. |
dependency .resource_type | string | The base type of this resource. |
dependency .name | string | The name of the task. |
dependency .resource_subtype | string | The 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_of | object | The task is the basic object around which many operations in Asana are centered. |
duplicate_of .gid | string | Globally unique identifier of the resource, as a string. |
duplicate_of .resource_type | string | The base type of this resource. |
duplicate_of .name | string | The name of the task. |
duplicate_of .resource_subtype | string | The 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_from | object | The task is the basic object around which many operations in Asana are centered. |
duplicated_from .gid | string | Globally unique identifier of the resource, as a string. |
duplicated_from .resource_type | string | The base type of this resource. |
duplicated_from .name | string | The name of the task. |
duplicated_from .resource_subtype | string | The 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 . |
follower | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
follower .gid | string | Globally unique identifier of the resource, as a string. |
follower .resource_type | string | The base type of this resource. |
follower .name | string | Read-only except when same user as requester. The user’s name. |
hearted | boolean | Deprecated - please use likes instead.Conditional. True if the story is hearted by the authorized user, false if not. |
hearts | object | Deprecated - please use likes instead.Conditional. Array of likes for users who have hearted this story. |
gid | string | Globally unique identifier of the object, as a string. |
user | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
user .gid | string | Globally unique identifier of the resource, as a string. |
user .resource_type | string | The base type of this resource. |
user .name | string | Read-only except when same user as requester. The user’s name. |
is_editable | boolean | Conditional. Whether the text of the story can be edited after creation. |
is_edited | boolean | Conditional. Whether the text of the story has been edited after creation. |
liked | boolean | Conditional. 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. |
» {} .gid | string | Globally unique identifier of the object, as a string. |
» {} .user | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
» {} .user .gid | string | Globally unique identifier of the resource, as a string. |
» {} .user .resource_type | string | The base type of this resource. |
» {} .user .name | string | Read-only except when same user as requester. The user’s name. |
new_approval_status | string | Conditional. The new value of approval status. |
new_date_value | object | Conditional The new value of a date custom field story. |
new_date_value .due_at | string(date-time)¦null | The 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_on | string(date) | The localized day on which this goal is due. This takes a date with format YYYY-MM-DD . |
new_date_value .start_on | string(date)¦null | The 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_dates | object | Conditional. |
new_dates .due_at | string(date-time)¦null | The 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_on | string(date) | The localized day on which this goal is due. This takes a date with format YYYY-MM-DD . |
new_dates .start_on | string(date)¦null | The 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_value | object | Enum 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 waspreviously 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 .gid | string | Globally unique identifier of the resource, as a string. |
new_enum_value .resource_type | string | The base type of this resource. |
new_enum_value .color | string | The color of the enum option. Defaults to none . |
new_enum_value .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
new_enum_value .name | string | The name of the enum option. |
new_multi_enum_values | [object] | Conditional. The new value of a multi_enum custom field story. |
» {} .gid | string | Globally unique identifier of the resource, as a string. |
» {} .resource_type | string | The base type of this resource. |
» {} .color | string | The color of the enum option. Defaults to none . |
» {} .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
» {} .name | string | The name of the enum option. |
new_name | string | Conditional. |
new_number_value | integer | Conditional. |
new_people_value | [object] | Conditional. The new value of a people custom field story. |
» {} .gid | string | Globally unique identifier of the resource, as a string. |
» {} .resource_type | string | The base type of this resource. |
» {} .name | string | Read-only except when same user as requester. The user’s name. |
new_resource_subtype | string | Conditional. |
new_section | object | A 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 .gid | string | Globally unique identifier of the resource, as a string. |
new_section .resource_type | string | The base type of this resource. |
new_section .name | string | The name of the section (i.e. the text displayed as the section header). |
new_text_value | string | Conditional. |
num_hearts | integer | Deprecated - please use likes instead.Conditional. The number of users who have hearted this story. |
num_likes | integer | Conditional. The number of users who have liked this story. |
old_approval_status | string | Conditional. The old value of approval status. |
old_date_value | object | Conditional. The old value of a date custom field story. |
old_date_value .due_at | string(date-time)¦null | The 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_on | string(date) | The localized day on which this goal is due. This takes a date with format YYYY-MM-DD . |
old_date_value .start_on | string(date)¦null | The 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_dates | object | Conditional. |
old_dates .due_at | string(date-time)¦null | The 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_on | string(date) | The localized day on which this goal is due. This takes a date with format YYYY-MM-DD . |
old_dates .start_on | string(date)¦null | The 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_value | object | Enum 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 waspreviously 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 .gid | string | Globally unique identifier of the resource, as a string. |
old_enum_value .resource_type | string | The base type of this resource. |
old_enum_value .color | string | The color of the enum option. Defaults to none . |
old_enum_value .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
old_enum_value .name | string | The name of the enum option. |
old_multi_enum_values | [object] | Conditional. The old value of a multi-enum custom field story. |
» {} .gid | string | Globally unique identifier of the resource, as a string. |
» {} .resource_type | string | The base type of this resource. |
» {} .color | string | The color of the enum option. Defaults to none . |
» {} .enabled | boolean | Whether or not the enum option is a selectable value for the custom field. |
» {} .name | string | The name of the enum option. |
old_name | string | Conditional. |
old_number_value | integer | Conditional |
old_people_value | [object] | Conditional. The old value of a people custom field story. |
» {} .gid | string | Globally unique identifier of the resource, as a string. |
» {} .resource_type | string | The base type of this resource. |
» {} .name | string | Read-only except when same user as requester. The user’s name. |
old_resource_subtype | string | Conditional. |
old_section | object | A 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 .gid | string | Globally unique identifier of the resource, as a string. |
old_section .resource_type | string | The base type of this resource. |
old_section .name | string | The name of the section (i.e. the text displayed as the section header). |
old_text_value | string | Conditional. |
previews | [object] | Conditional. A collection of previews to be displayed in the story. Note: This property only exists for comment stories. |
» {} .fallback | string | Some fallback text to display if unable to display the full preview. |
» {} .footer | string | Text to display in the footer. |
» {} .header | string | Text to display in the header. |
» {} .header_link | string | Where the header will link to. |
» {} .html_text | string | HTML formatted text for the body of the preview. |
» {} .text | string | Text for the body of the preview. |
» {} .title | string | Text to display as the title. |
» {} .title_link | string | Where to title will link to. |
project | object | A 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 .gid | string | Globally unique identifier of the resource, as a string. |
project .resource_type | string | The base type of this resource. |
project .name | string | Name 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. |
source | string | The component of the Asana product the user used to trigger the story. |
story | object | A story represents an activity associated with an object in the Asana system. |
story .gid | string | Globally unique identifier of the resource, as a string. |
story .resource_type | string | The base type of this resource. |
story .created_at | string(date-time) | The time at which this resource was created. |
story .created_by | object | A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks. |
story .created_by .gid | string | Globally unique identifier of the resource, as a string. |
story .created_by .resource_type | string | The base type of this resource. |
story .created_by .name | string | Read-only except when same user as requester. The user’s name. |
story .resource_subtype | string | The 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 .text | string | Create-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. |
tag | object | A tag is a label that can be attached to any task in Asana. It exists in a single workspace or organization. |
tag .gid | string | Globally unique identifier of the resource, as a string. |
tag .resource_type | string | The base type of this resource. |
tag .name | string | Name 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. |
target | object | The object this story is associated with. Currently may only be a task. |
target .gid | string | Globally unique identifier of the resource, as a string. |
target .resource_type | string | The base type of this resource. |
target .name | string | The name of the task. |
target .resource_subtype | string | The 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 . |
task | object | The task is the basic object around which many operations in Asana are centered. |
task .gid | string | Globally unique identifier of the resource, as a string. |
task .resource_type | string | The base type of this resource. |
task .name | string | The name of the task. |
task .resource_subtype | string | The 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 . |
type | string | none |
{
"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"
}