Skip to content

Asana: Goals schemas

19 Asana schemas with complete fields and constraints.

← Goals operations · All schemas

Create a goal metric — request body — body data

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
resource_subtypestringOptionalThe 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.
Read only: true
One of: number
precisionintegerOptional*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.
For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.
unitstringOptionalA supported unit of measure for the goal metric, or none.
One of: none, currency, percentage
currency_codeJSONOptional
currency_code (anyOf 1)stringAlternativeISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.
currency_code (anyOf 2)nullAlternative
initial_number_valuenumberOptionalThis number is the start value of a goal metric of type number.
target_number_valuenumberOptionalThis number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.
current_number_valuenumberOptionalThis number is the current value of a goal metric of type number.
current_display_valuestringOptionalThis string is the current value of a goal metric of type string.
Read only: true
progress_sourcestringOptionalThis field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.
One of: manual, subgoal_progress, project_task_completion, project_milestone_completion, task_completion, external
is_custom_weightbooleanOptional*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted

Create a goal — request body — body data

FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Create a goal — request body — body data due on, gid, html notes, is workspace level, liked, name, notes, owner, resource type, start on, team, time period, workspace
$ (allOf 2)objectAll variants apply
$ (allOf 2).followersarrayOptional
$ (allOf 2).followers[]stringEach itemThe `gid` of a user.

Referenced models: Create a goal — request body — body data due on, gid, html notes, is workspace level, liked, name, notes, owner, resource type, start on, team, time period, workspace

Create a goal — request body — body data due on, gid, html notes, is workspace level, liked, name, notes, owner, resource type, start on, team, time period, workspace

FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on
$ (allOf 2)objectAll variants apply
$ (allOf 2).teamJSONOptional
$ (allOf 2).team (anyOf 1)stringAlternative*Conditional*. This property is only present when the `workspace` provided is an organization.
$ (allOf 2).team (anyOf 2)nullAlternative
$ (allOf 2).workspacestringOptionalThe `gid` of a workspace.
$ (allOf 2).time_periodJSONOptional
$ (allOf 2).time_period (anyOf 1)stringAlternativeThe `gid` of a time period.
$ (allOf 2).time_period (anyOf 2)nullAlternative
$ (allOf 2).ownerJSONOptional
$ (allOf 2).owner (anyOf 1)stringAlternativeThe `gid` of a user.
$ (allOf 2).owner (anyOf 2)nullAlternative

Referenced models: Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on

Get a goal — request body — query

FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
opt_prettybooleanOptional
opt_fieldsarrayOptional
opt_fields[]stringEach itemOne of: current_status_update, current_status_update.resource_subtype, current_status_update.title, custom_field_settings, custom_field_settings.custom_field, custom_field_settings.custom_field.asana_created_field, custom_field_settings.custom_field.created_by, custom_field_settings.custom_field.created_by.name, custom_field_settings.custom_field.currency_code, custom_field_settings.custom_field.custom_label, custom_field_settings.custom_field.custom_label_position, custom_field_settings.custom_field.date_value, custom_field_settings.custom_field.date_value.date, custom_field_settings.custom_field.date_value.date_time, custom_field_settings.custom_field.default_access_level, custom_field_settings.custom_field.description, custom_field_settings.custom_field.display_value, custom_field_settings.custom_field.enabled, custom_field_settings.custom_field.enum_options, custom_field_settings.custom_field.enum_options.color, custom_field_settings.custom_field.enum_options.enabled, custom_field_settings.custom_field.enum_options.name, custom_field_settings.custom_field.enum_value, custom_field_settings.custom_field.enum_value.color, custom_field_settings.custom_field.enum_value.enabled, custom_field_settings.custom_field.enum_value.name, custom_field_settings.custom_field.format, custom_field_settings.custom_field.has_notifications_enabled, custom_field_settings.custom_field.html_text_value, custom_field_settings.custom_field.id_prefix, custom_field_settings.custom_field.input_restrictions, custom_field_settings.custom_field.is_formula_field, custom_field_settings.custom_field.is_global_to_workspace, custom_field_settings.custom_field.is_lookup_field, custom_field_settings.custom_field.is_value_read_only, custom_field_settings.custom_field.multi_enum_values, custom_field_settings.custom_field.multi_enum_values.color, custom_field_settings.custom_field.multi_enum_values.enabled, custom_field_settings.custom_field.multi_enum_values.name, custom_field_settings.custom_field.name, custom_field_settings.custom_field.number_value, custom_field_settings.custom_field.people_value, custom_field_settings.custom_field.people_value.name, custom_field_settings.custom_field.precision, custom_field_settings.custom_field.privacy_setting, custom_field_settings.custom_field.reference_value, custom_field_settings.custom_field.reference_value.name, custom_field_settings.custom_field.representation_type, custom_field_settings.custom_field.resource_subtype, custom_field_settings.custom_field.text_value, custom_field_settings.custom_field.type, custom_field_settings.is_important, custom_field_settings.parent, custom_field_settings.parent.name, custom_field_settings.parent.resource_subtype, custom_field_settings.project, custom_field_settings.project.name, custom_field_settings.project.resource_subtype, custom_fields, custom_fields.date_value, custom_fields.date_value.date, custom_fields.date_value.date_time, custom_fields.display_value, custom_fields.enabled, custom_fields.enum_options, custom_fields.enum_options.color, custom_fields.enum_options.enabled, custom_fields.enum_options.name, custom_fields.enum_value, custom_fields.enum_value.color, custom_fields.enum_value.enabled, custom_fields.enum_value.name, custom_fields.id_prefix, custom_fields.input_restrictions, custom_fields.is_formula_field, custom_fields.is_lookup_field, custom_fields.multi_enum_values, custom_fields.multi_enum_values.color, custom_fields.multi_enum_values.enabled, custom_fields.multi_enum_values.name, custom_fields.name, custom_fields.number_value, custom_fields.representation_type, custom_fields.text_value, custom_fields.type, default_access_level, due_on, followers, followers.name, html_notes, is_workspace_level, liked, likes, likes.user, likes.user.name, metric, metric.can_manage, metric.currency_code, metric.current_display_value, metric.current_number_value, metric.initial_number_value, metric.is_custom_weight, metric.precision, metric.progress_source, metric.resource_subtype, metric.target_number_value, metric.unit, name, notes, num_likes, owner, owner.name, privacy_setting, start_on, status, team, team.name, time_period, time_period.display_name, time_period.end_on, time_period.period, time_period.start_on, workspace, workspace.name

Get a goal — response body — data

FieldTypePresenceDescription and constraints
$objectRoot
dataModelRequired within parentExpand Get a goal — response body — data data — sdk__Goal Response

Referenced models: Get a goal — response body — data data — sdk__Goal Response

Get a goal — response body — data / data / default_access_level: admin, editor, commenter, viewer, privacy setting: public to workspace, members only metric resource subtype: number, unit: none, currency, percentage resource subtype: number, unit: none, currency, percentage

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
resource_subtypestringOptionalThe 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.
Known values: number
Read only: true
precisionJSONOptional
precision (anyOf 1)integerAlternative*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.
For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.
precision (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
unitstringOptionalA supported unit of measure for the goal metric, or none.
Known values: none, currency, percentage
currency_codeJSONOptional
currency_code (anyOf 1)stringAlternativeISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.
currency_code (anyOf 2)nullAlternative
initial_number_valueJSONOptional
initial_number_value (anyOf 1)numberAlternativeThis number is the start value of a goal metric of type number.
initial_number_value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
target_number_valueJSONOptional
target_number_value (anyOf 1)numberAlternativeThis number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.
target_number_value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
current_number_valueJSONOptional
current_number_value (anyOf 1)numberAlternativeThis number is the current value of a goal metric of type number.
current_number_value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
current_display_valuestringOptionalThis string is the current value of a goal metric of type string.
Read only: true
progress_sourcestringOptionalThis field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.
Known values: manual, subgoal_progress, project_task_completion, project_milestone_completion, task_completion, external
is_custom_weightbooleanOptional*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted

Get a goal — response body — data data custom field settings item

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.A generic Asana Resource, containing a globally unique identifier.
Custom Fields Settings objects represent the many-to-many join of the Custom Field and Project as well as stores information that is relevant to that particular pairing.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
projectModelOptionalExpand Add a custom field to a project — response body — data data project
is_importantbooleanOptional`is_important` is used in the Asana web application to determine if this custom field is displayed in the list/grid view of a project or portfolio.
Read only: true
parentModelOptionalExpand Add a custom field to a project — response body — data data parent
custom_fieldModelOptionalExpand Add a custom field to a project — response body — data data custom field

Referenced models: Add a custom field to a project — response body — data data custom field, Add a custom field to a project — response body — data data parent, Add a custom field to a project — response body — data data project

Get a goal — response body — data data custom fields item

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.A generic Asana Resource, containing a globally unique identifier.
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](/reference/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.

Users in Asana can [lock custom fields](https://asana.com/guide/help/premium/custom-fields#gl-lock-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`.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the custom field.
typestringOptional*Deprecated: new integrations should prefer the resource_subtype field.* The type of the custom field. Must be one of the given values.

Known values: text, enum, multi_enum, number, date, people, reference
Read only: true
enum_optionsarrayOptional*Conditional*. Only relevant for custom fields of type `enum` or `multi_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](/reference/createenumoptionforcustomfield).
enum_options[]ModelEach itemExpand Get a custom field — response body — data data enum options item
enabledbooleanOptional*Conditional*. This field applies only to [custom field values](/docs/custom-fields-guide#/accessing-custom-field-values-on-tasks-or-projects) and is not available for [custom field definitions](/docs/custom-fields-guide#/accessing-custom-field-definitions).
Determines if the custom field is enabled or not. For more details, see the [Custom Fields documentation](/docs/custom-fields-guide#/enabled-and-disabled-values).
Read only: true
representation_typestringOptionalThis field tells the type of the custom field.
Known values: text, enum, multi_enum, number, date, people, formula, custom_id, reference
Read only: true
id_prefixJSONOptional
id_prefix (anyOf 1)stringAlternativeThis field is the unique custom ID string for the custom field.
id_prefix (anyOf 2)nullAlternative
input_restrictionsarrayOptional
input_restrictions[]stringEach item*Conditional*. Only relevant for custom fields of type `reference`. This array of strings reflects the allowed types of objects that can be written to a `reference` custom field value.
Known values: task, project, portfolio, goal
is_formula_fieldbooleanOptional*Conditional*. This flag describes whether a custom field is a formula custom field.
is_lookup_fieldbooleanOptional*Conditional*. This flag describes whether a custom field is a lookup custom field.
date_valueJSONOptional
date_value (anyOf 1)ModelAlternativeExpand Get a custom field — response body — data data date value date, date time
date_value (anyOf 2)nullAlternative
enum_valueJSONOptional
enum_value (anyOf 1)ModelAlternativeExpand Get a custom field — response body — data data enum value color, enabled, gid, name, resource type
enum_value (anyOf 2)nullAlternative
multi_enum_valuesarrayOptional*Conditional*. Only relevant for custom fields of type `multi_enum`. This object is the chosen values of a `multi_enum` custom field.
multi_enum_values[]ModelEach itemExpand Get a custom field — response body — data data enum options item
number_valueJSONOptional
number_value (anyOf 1)JSONAlternative
number_value (anyOf 1) (anyOf 1)numberAlternative*Conditional*. This number is the value of a `number` custom field.
number_value (anyOf 1) (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
number_value (anyOf 2)nullAlternative
text_valueJSONOptional
text_value (anyOf 1)stringAlternative*Conditional*. This string is the value of a `text` custom field.
text_value (anyOf 2)nullAlternative
display_valueJSONOptional
display_value (anyOf 1)stringAlternativeA 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.
Read only: true
display_value (anyOf 2)nullAlternative

Referenced models: Get a custom field — response body — data data date value date, date time, Get a custom field — response body — data data enum options item, Get a custom field — response body — data data enum value color, enabled, gid, name, resource type

Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the goal.
html_notesstringOptionalThe notes of the goal with formatting as HTML. See [rich text](/docs/rich-text).
notesstringOptionalFree-form textual information associated with the goal (i.e. its description).
due_onJSONOptional
due_on (anyOf 1)stringAlternativeThe localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.
due_on (anyOf 2)nullAlternative
start_onJSONOptional
start_on (anyOf 1)stringAlternativeThe 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.
start_on (anyOf 2)nullAlternative
is_workspace_levelbooleanOptional*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace’s goals) or not. If it isn’t a workspace-level goal, it is a team-level goal, and is associated with the goal’s team.
likedbooleanOptionalTrue if the goal is liked by the authorized user, false if not.

Get a goal — response body — data data likes item

FieldTypePresenceDescription and constraints
$objectRootAn object to represent a user's like.
gidstringOptionalGlobally unique identifier of the object, as a string.
Read only: true
userModelOptionalExpand Get an OOO entry — response body — data data user

Referenced models: Get an OOO entry — response body — data data user

Get a goal — response body — data data team gid, name, resource type

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.A generic Asana Resource, containing a globally unique identifier.
A *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.A generic Asana Resource, containing a globally unique identifier.A generic Asana Resource, containing a globally unique identifier.
A *team* is used to group related projects and people together within an organization. Each project in an organization is associated with a team.
*Conditional*. This property is only present when the `workspace` provided is an organization.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the team.

Get a goal — response body — data data — Goal Response

FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on
$ (allOf 2)objectAll variants apply
$ (allOf 2).likesarrayOptionalArray of likes for users who have liked this goal.
Read only: true
$ (allOf 2).likes[]ModelEach itemExpand Get a story — response body — data / data / source: web, email, mobile, api, unknown, type: comment, system likes item
$ (allOf 2).num_likesJSONOptional
$ (allOf 2).num_likes (anyOf 1)integerAlternativeThe number of users who have liked this goal.
Read only: true
$ (allOf 2).num_likes (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (allOf 2).teamJSONOptional
$ (allOf 2).team (anyOf 1)JSONAlternative
$ (allOf 2).team (anyOf 1) (allOf 1)ModelAll variants applyExpand Add a user to a team — response body — data data team — Team Compact
$ (allOf 2).team (anyOf 1) (allOf 2)objectAll variants apply*Conditional*. This property is only present when the `workspace` provided is an organization.
$ (allOf 2).team (anyOf 2)nullAlternative
$ (allOf 2).workspaceJSONOptional
$ (allOf 2).workspace (allOf 1)ModelAll variants applyExpand Update a workspace — request body — body data
$ (allOf 2).workspace (allOf 2)objectAll variants apply
$ (allOf 2).followersarrayOptionalArray of users who are members of this goal.
$ (allOf 2).followers[]ModelEach itemExpand Get users in a team — response body — data data item
$ (allOf 2).time_periodJSONOptional
$ (allOf 2).time_period (anyOf 1)JSONAlternative
$ (allOf 2).time_period (anyOf 1) (allOf 1)ModelAll variants applyExpand Get time periods — response body — data, next page data item
$ (allOf 2).time_period (anyOf 1) (allOf 2)objectAll variants apply
$ (allOf 2).time_period (anyOf 2)nullAlternative
$ (allOf 2).metricJSONOptional
$ (allOf 2).metric (anyOf 1)JSONAlternative
$ (allOf 2).metric (anyOf 1) (allOf 1)ModelAll variants applyExpand Get a goal — response body — data / data / default_access_level: admin, editor, commenter, viewer, privacy setting: public to workspace, members only metric resource subtype: number, unit: none, currency, percentage resource subtype: number, unit: none, currency, percentage
$ (allOf 2).metric (anyOf 1) (allOf 2)objectAll variants apply
$ (allOf 2).metric (anyOf 1) (allOf 2).can_managebooleanOptional*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.
Read only: true
$ (allOf 2).metric (anyOf 2)nullAlternative
$ (allOf 2).ownerJSONOptional
$ (allOf 2).owner (anyOf 1)JSONAlternative
$ (allOf 2).owner (anyOf 1) (allOf 1)ModelAll variants applyExpand Get users in a team — response body — data data item
$ (allOf 2).owner (anyOf 1) (allOf 2)objectAll variants apply
$ (allOf 2).owner (anyOf 2)nullAlternative
$ (allOf 2).current_status_updateJSONOptional
$ (allOf 2).current_status_update (anyOf 1)JSONAlternative
$ (allOf 2).current_status_update (anyOf 1) (allOf 1)ModelAll variants applyExpand Get status updates from an object — response body — data, next page data item
$ (allOf 2).current_status_update (anyOf 1) (allOf 2)JSONAll variants applyThe latest `status_update` posted to this goal.
$ (allOf 2).current_status_update (anyOf 2)nullAlternative
$ (allOf 2).statusJSONOptional
$ (allOf 2).status (anyOf 1)stringAlternativeThe current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect "On Track", "At Risk", and "Off Track", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.
*Note* you can only write to this property if `metric` is set.
Read only: true
$ (allOf 2).status (anyOf 2)nullAlternative
$ (allOf 2).privacy_settingstringOptionalThe privacy setting of the goal.
Known values: public_to_workspace, members_only
$ (allOf 2).default_access_levelstringOptionalThe default access level when inviting new members to the goal
Known values: admin, editor, commenter, viewer
$ (allOf 2).custom_fieldsarrayOptionalArray of custom field values applied directly to the goal itself. These represent the values set on the goal, not the fields available for items in the goal.
$ (allOf 2).custom_fields[]ModelEach itemExpand Get a membership — response body — data / data / access_level: admin, editor, user parent
$ (allOf 2).custom_field_settingsarrayOptionalArray of custom field definitions that are enabled for the goal. These represent which custom fields are available to be used on items within the goal, but do not include any values.
$ (allOf 2).custom_field_settings[]ModelEach itemExpand Add a custom field to a project — response body — data data — Custom Field Setting Response

Referenced models: Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on, Get a story — response body — data / data / source: web, email, mobile, api, unknown, type: comment, system likes item, Get a membership — response body — data / data / access_level: admin, editor, user parent, Add a custom field to a project — response body — data data — Custom Field Setting Response, Get a goal — response body — data / data / default_access_level: admin, editor, commenter, viewer, privacy setting: public to workspace, members only metric resource subtype: number, unit: none, currency, percentage resource subtype: number, unit: none, currency, percentage, Get status updates from an object — response body — data, next page data item, Add a user to a team — response body — data data team — Team Compact, Get time periods — response body — data, next page data item, Get users in a team — response body — data data item, Update a workspace — request body — body data

Get a goal — response body — data data — sdk__Goal Response

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the goal.
html_notesstringOptionalThe notes of the goal with formatting as HTML. See [rich text](/docs/rich-text).
notesstringOptionalFree-form textual information associated with the goal (i.e. its description).
due_onJSONOptional
due_on (anyOf 1)stringAlternativeThe localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`.
due_on (anyOf 2)nullAlternative
start_onJSONOptional
start_on (anyOf 1)stringAlternativeThe 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.
start_on (anyOf 2)nullAlternative
is_workspace_levelbooleanOptional*Conditional*. This property is only present when the `workspace` provided is an organization. Whether the goal belongs to the `workspace` (and is listed as part of the workspace’s goals) or not. If it isn’t a workspace-level goal, it is a team-level goal, and is associated with the goal’s team.
likedbooleanOptionalTrue if the goal is liked by the authorized user, false if not.
likesarrayOptionalArray of likes for users who have liked this goal.
Read only: true
likes[]ModelEach itemExpand Get a goal — response body — data data likes item
num_likesJSONOptional
num_likes (anyOf 1)integerAlternativeThe number of users who have liked this goal.
Read only: true
num_likes (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
teamJSONOptional
team (anyOf 1)ModelAlternativeExpand Get a goal — response body — data data team gid, name, resource type
team (anyOf 2)nullAlternative
workspaceModelOptionalExpand Get a tag — response body — data data workspace
followersarrayOptionalArray of users who are members of this goal.
followers[]ModelEach itemExpand Get an OOO entry — response body — data data user
time_periodJSONOptional
time_period (anyOf 1)ModelAlternativeExpand Get a time period — response body — data / data / parent / period: FY, H1, H2, Q1, Q2, Q3, Q4
time_period (anyOf 2)nullAlternative
metricJSONOptional
metric (anyOf 1)objectAlternativeA generic Asana Resource, containing a globally unique identifier.
metric (anyOf 1).gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
metric (anyOf 1).resource_typestringOptionalThe base type of this resource.
Read only: true
metric (anyOf 1).resource_subtypestringOptionalThe 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.
Known values: number
Read only: true
metric (anyOf 1).precisionJSONOptional
metric (anyOf 1).precision (anyOf 1)integerAlternative*Conditional*. Only relevant for goal metrics of type `Number`. This field dictates the number of places after the decimal to round to, i.e. 0 is integer values, 1 rounds to the nearest tenth, and so on. Must be between 0 and 6, inclusive.
For percentage format, this may be unintuitive, as a value of 0.25 has a precision of 0, while a value of 0.251 has a precision of 1. This is due to 0.25 being displayed as 25%.
metric (anyOf 1).precision (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
metric (anyOf 1).unitstringOptionalA supported unit of measure for the goal metric, or none.
Known values: none, currency, percentage
metric (anyOf 1).currency_codeJSONOptional
metric (anyOf 1).currency_code (anyOf 1)stringAlternativeISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`.
metric (anyOf 1).currency_code (anyOf 2)nullAlternative
metric (anyOf 1).initial_number_valueJSONOptional
metric (anyOf 1).initial_number_value (anyOf 1)numberAlternativeThis number is the start value of a goal metric of type number.
metric (anyOf 1).initial_number_value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
metric (anyOf 1).target_number_valueJSONOptional
metric (anyOf 1).target_number_value (anyOf 1)numberAlternativeThis number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`.
metric (anyOf 1).target_number_value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
metric (anyOf 1).current_number_valueJSONOptional
metric (anyOf 1).current_number_value (anyOf 1)numberAlternativeThis number is the current value of a goal metric of type number.
metric (anyOf 1).current_number_value (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
metric (anyOf 1).current_display_valuestringOptionalThis string is the current value of a goal metric of type string.
Read only: true
metric (anyOf 1).progress_sourcestringOptionalThis field defines how the progress value of a goal metric is being calculated. A goal's progress can be provided manually by the user, calculated automatically from contributing subgoals, projects, or tasks, or managed by an integration with an external data source, such as Salesforce.
Known values: manual, subgoal_progress, project_task_completion, project_milestone_completion, task_completion, external
metric (anyOf 1).is_custom_weightbooleanOptional*Conditional*. Only relevant if `metric.progress_source` is one of `subgoal_progress`, `project_task_completion`, `project_milestone_completion`, or `task_completion`. If true, we use the supporting object's custom weight to calculate the goal's progress. If false, we treat all supporting objects as equally weighted
metric (anyOf 1).can_managebooleanOptional*Conditional*. Only relevant for `progress_source` of type `external`. This boolean indicates whether the requester has the ability to update the current value of this metric. This returns `true` if the external metric was created by the requester, `false` otherwise.
Read only: true
metric (anyOf 2)nullAlternative
ownerJSONOptional
owner (anyOf 1)ModelAlternativeExpand Get an OOO entry — response body — data data user
owner (anyOf 2)nullAlternative
current_status_updateJSONOptional
current_status_update (anyOf 1)objectAlternativeA generic Asana Resource, containing a globally unique identifier.A generic Asana Resource, containing a globally unique identifier.
A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the object.A generic Asana Resource, containing a globally unique identifier.A generic Asana Resource, containing a globally unique identifier.
A *status update* is an update on the progress of a particular project, portfolio, or goal, and is sent out to all of its parent's followers when created. These updates include both text describing the update and a `status_type` intended to represent the overall state of the object.
The latest `status_update` posted to this goal.
current_status_update (anyOf 1).gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
current_status_update (anyOf 1).resource_typestringOptionalThe base type of this resource.
Read only: true
current_status_update (anyOf 1).titlestringOptionalThe title of the status update.
current_status_update (anyOf 1).resource_subtypestringOptionalThe 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`s for `status` objects represent the type of their parent.
Known values: project_status_update, portfolio_status_update, goal_status_update
Read only: true
current_status_update (anyOf 2)nullAlternative
statusJSONOptional
status (anyOf 1)stringAlternativeThe current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect "On Track", "At Risk", and "Off Track", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.
*Note* you can only write to this property if `metric` is set.
Read only: true
status (anyOf 2)nullAlternative
privacy_settingstringOptionalThe privacy setting of the goal.
Known values: public_to_workspace, members_only
default_access_levelstringOptionalThe default access level when inviting new members to the goal
Known values: admin, editor, commenter, viewer
custom_fieldsarrayOptionalArray of custom field values applied directly to the goal itself. These represent the values set on the goal, not the fields available for items in the goal.
custom_fields[]ModelEach itemExpand Get a goal — response body — data data custom fields item
custom_field_settingsarrayOptionalArray of custom field definitions that are enabled for the goal. These represent which custom fields are available to be used on items within the goal, but do not include any values.
custom_field_settings[]ModelEach itemExpand Get a goal — response body — data data custom field settings item

Referenced models: Get an OOO entry — response body — data data user, Get a goal — response body — data data custom fields item, Get a goal — response body — data data likes item, Get a goal — response body — data data custom field settings item, Get a goal — response body — data data team gid, name, resource type, Get a time period — response body — data / data / parent / period: FY, H1, H2, Q1, Q2, Q3, Q4, Get a tag — response body — data data workspace

Get goals — response body — data, next page

FieldTypePresenceDescription and constraints
$objectRoot
dataarrayRequired within parent
data[]ModelEach itemExpand Get a goal — response body — data data — sdk__Goal Response
next_pageModelOptionalExpand Get goals — response body — data, next page next page

Referenced models: Get goals — response body — data, next page next page, Get a goal — response body — data data — sdk__Goal Response

Get goals — response body — data, next page next page

FieldTypePresenceDescription and constraints
$JSONRoot
$ (anyOf 1)objectAlternative*Conditional*. This property is only present when a limit query parameter is provided in the request. When making a paginated request, the API will return a number of results as specified by the limit parameter. If more results exist, then the response will contain a next_page attribute, which will include an offset, a relative path attribute, and a full uri attribute. If there are no more pages available, next_page will be null and no offset will be provided. Note that an offset token will expire after some time, as data may have changed.
$ (anyOf 1).offsetstringOptionalPagination offset for the request.
Read only: true
$ (anyOf 1).pathstringOptionalA relative path containing the query parameters to fetch for next_page
Read only: true
$ (anyOf 1).uristringOptionalA full uri containing the query parameters to fetch for next_page
Format: uri
Read only: true
$ (anyOf 2)nullAlternative

Get parent goals from a goal — response body — data data item

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
namestringOptionalThe name of the goal.
ownerJSONOptional
owner (anyOf 1)JSONAlternative
owner (anyOf 1) (allOf 1)ModelAll variants applyExpand Get users in a team — response body — data data item
owner (anyOf 1) (allOf 2)objectAll variants apply
owner (anyOf 2)nullAlternative

Referenced models: Get users in a team — response body — data data item

Remove a custom field from a goal — request body — body data

FieldTypePresenceDescription and constraints
$objectRoot
custom_fieldstringRequired within parentThe custom field to remove from this portfolio.

Update a goal metric — request body — body data

FieldTypePresenceDescription and constraints
$objectRootA generic Asana Resource, containing a globally unique identifier.
gidstringOptionalGlobally unique identifier of the resource, as a string.
Read only: true
resource_typestringOptionalThe base type of this resource.
Read only: true
current_number_valuenumberOptional*Conditional*. This number is the current value of a goal metric of type number.

Update a goal — request body — body data

FieldTypePresenceDescription and constraints
$JSONRoot
$ (allOf 1)ModelAll variants applyExpand Create a goal — request body — body data due on, gid, html notes, is workspace level, liked, name, notes, owner, resource type, start on, team, time period, workspace
$ (allOf 2)objectAll variants apply
$ (allOf 2).statusJSONOptional
$ (allOf 2).status (anyOf 1)stringAlternativeThe current status of this goal. When the goal is open, its status can be `green`, `yellow`, and `red` to reflect "On Track", "At Risk", and "Off Track", respectively. When the goal is closed, the value can be `missed`, `achieved`, `partial`, or `dropped`.
*Note* you can only write to this property if `metric` is set.
$ (allOf 2).status (anyOf 2)nullAlternative
$ (allOf 2).custom_fieldsobjectOptionalAn object where each key is the GID of a custom field and its corresponding value is either an enum GID, string, number, or object (depending on the custom field type). See the [custom fields guide](/docs/custom-fields-guide) for details on creating and updating custom field values.
Additional keys: see wildcard field
$ (allOf 2).custom_fields.*stringAdditional keys"{custom_field_gid}" => Value (can be text, enum GID, a number, etc.). For date, use format "YYYY-MM-DD" (e.g., 2019-09-15). For date-time, use ISO 8601 date string in UTC (e.g., 2019-09-15T02:06:58.147Z).
$ (allOf 2).html_custom_fieldsobjectOptionalAn object where each key is the GID of a text custom field and the corresponding value is a rich text HTML string. Only text-type custom fields support this parameter. Values must be wrapped in <body></body> tags. See the [custom fields guide](/docs/custom-fields-guide) and [rich text](/docs/rich-text) for details on supported formatting.
Additional keys: see wildcard field
$ (allOf 2).html_custom_fields.*stringAdditional keys"{custom_field_gid}" => HTML string (e.g., "<body>Text content</body>")

Referenced models: Create a goal — request body — body data due on, gid, html notes, is workspace level, liked, name, notes, owner, resource type, start on, team, time period, workspace

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.