Asana: Goals schemas
19 Asana schemas with complete fields and constraints.
← Goals operations · All schemas
Create a goal metric — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A generic Asana Resource, containing a globally unique identifier. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
resource_subtype | string | Optional | 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. Read only: true One of: number |
precision | integer | Optional | *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%. |
unit | string | Optional | A supported unit of measure for the goal metric, or none. One of: none, currency, percentage |
currency_code | JSON | Optional | |
currency_code (anyOf 1) | string | Alternative | ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`. |
currency_code (anyOf 2) | null | Alternative | |
initial_number_value | number | Optional | This number is the start value of a goal metric of type number. |
target_number_value | number | Optional | This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`. |
current_number_value | number | Optional | This number is the current value of a goal metric of type number. |
current_display_value | string | Optional | This string is the current value of a goal metric of type string. Read only: true |
progress_source | string | Optional | This 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_weight | boolean | Optional | *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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand 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) | object | All variants apply | |
$ (allOf 2).followers | array | Optional | |
$ (allOf 2).followers[] | string | Each item | The `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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on |
$ (allOf 2) | object | All variants apply | |
$ (allOf 2).team | JSON | Optional | |
$ (allOf 2).team (anyOf 1) | string | Alternative | *Conditional*. This property is only present when the `workspace` provided is an organization. |
$ (allOf 2).team (anyOf 2) | null | Alternative | |
$ (allOf 2).workspace | string | Optional | The `gid` of a workspace. |
$ (allOf 2).time_period | JSON | Optional | |
$ (allOf 2).time_period (anyOf 1) | string | Alternative | The `gid` of a time period. |
$ (allOf 2).time_period (anyOf 2) | null | Alternative | |
$ (allOf 2).owner | JSON | Optional | |
$ (allOf 2).owner (anyOf 1) | string | Alternative | The `gid` of a user. |
$ (allOf 2).owner (anyOf 2) | null | Alternative |
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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
opt_pretty | boolean | Optional | |
opt_fields | array | Optional | |
opt_fields[] | string | Each item | One 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | Model | Required within parent | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A generic Asana Resource, containing a globally unique identifier. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
resource_subtype | string | Optional | 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. Known values: number Read only: true |
precision | JSON | Optional | |
precision (anyOf 1) | integer | Alternative | *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) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
unit | string | Optional | A supported unit of measure for the goal metric, or none. Known values: none, currency, percentage |
currency_code | JSON | Optional | |
currency_code (anyOf 1) | string | Alternative | ISO 4217 currency code to format this custom field. This will be null if the `unit` is not `currency`. |
currency_code (anyOf 2) | null | Alternative | |
initial_number_value | JSON | Optional | |
initial_number_value (anyOf 1) | number | Alternative | This number is the start value of a goal metric of type number. |
initial_number_value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
target_number_value | JSON | Optional | |
target_number_value (anyOf 1) | number | Alternative | This number is the end value of a goal metric of type number. This number cannot equal `initial_number_value`. |
target_number_value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
current_number_value | JSON | Optional | |
current_number_value (anyOf 1) | number | Alternative | This number is the current value of a goal metric of type number. |
current_number_value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
current_display_value | string | Optional | This string is the current value of a goal metric of type string. Read only: true |
progress_source | string | Optional | This 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_weight | boolean | Optional | *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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A 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. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
project | Model | Optional | Expand Add a custom field to a project — response body — data data project |
is_important | boolean | Optional | `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 |
parent | Model | Optional | Expand Add a custom field to a project — response body — data data parent |
custom_field | Model | Optional | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A 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`. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the custom field. |
type | string | Optional | *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_options | array | Optional | *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[] | Model | Each item | Expand Get a custom field — response body — data data enum options item |
enabled | boolean | Optional | *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_type | string | Optional | This 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_prefix | JSON | Optional | |
id_prefix (anyOf 1) | string | Alternative | This field is the unique custom ID string for the custom field. |
id_prefix (anyOf 2) | null | Alternative | |
input_restrictions | array | Optional | |
input_restrictions[] | string | Each 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_field | boolean | Optional | *Conditional*. This flag describes whether a custom field is a formula custom field. |
is_lookup_field | boolean | Optional | *Conditional*. This flag describes whether a custom field is a lookup custom field. |
date_value | JSON | Optional | |
date_value (anyOf 1) | Model | Alternative | Expand Get a custom field — response body — data data date value date, date time |
date_value (anyOf 2) | null | Alternative | |
enum_value | JSON | Optional | |
enum_value (anyOf 1) | Model | Alternative | Expand Get a custom field — response body — data data enum value color, enabled, gid, name, resource type |
enum_value (anyOf 2) | null | Alternative | |
multi_enum_values | array | Optional | *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[] | Model | Each item | Expand Get a custom field — response body — data data enum options item |
number_value | JSON | Optional | |
number_value (anyOf 1) | JSON | Alternative | |
number_value (anyOf 1) (anyOf 1) | number | Alternative | *Conditional*. This number is the value of a `number` custom field. |
number_value (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
number_value (anyOf 2) | null | Alternative | |
text_value | JSON | Optional | |
text_value (anyOf 1) | string | Alternative | *Conditional*. This string is the value of a `text` custom field. |
text_value (anyOf 2) | null | Alternative | |
display_value | JSON | Optional | |
display_value (anyOf 1) | string | Alternative | 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. Read only: true |
display_value (anyOf 2) | null | Alternative |
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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A generic Asana Resource, containing a globally unique identifier. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the goal. |
html_notes | string | Optional | The notes of the goal with formatting as HTML. See [rich text](/docs/rich-text). |
notes | string | Optional | Free-form textual information associated with the goal (i.e. its description). |
due_on | JSON | Optional | |
due_on (anyOf 1) | string | Alternative | The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`. |
due_on (anyOf 2) | null | Alternative | |
start_on | JSON | Optional | |
start_on (anyOf 1) | string | Alternative | 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. |
start_on (anyOf 2) | null | Alternative | |
is_workspace_level | boolean | Optional | *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. |
liked | boolean | Optional | True if the goal is liked by the authorized user, false if not. |
Get a goal — response body — data data likes item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | An object to represent a user's like. |
gid | string | Optional | Globally unique identifier of the object, as a string. Read only: true |
user | Model | Optional | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | 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.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. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the team. |
Get a goal — response body — data data — Goal Response
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand Get a goal — response body — data data due on, gid, html notes, is workspace level, liked, name, notes, resource type, start on |
$ (allOf 2) | object | All variants apply | |
$ (allOf 2).likes | array | Optional | Array of likes for users who have liked this goal. Read only: true |
$ (allOf 2).likes[] | Model | Each item | Expand Get a story — response body — data / data / source: web, email, mobile, api, unknown, type: comment, system likes item |
$ (allOf 2).num_likes | JSON | Optional | |
$ (allOf 2).num_likes (anyOf 1) | integer | Alternative | The number of users who have liked this goal. Read only: true |
$ (allOf 2).num_likes (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
$ (allOf 2).team | JSON | Optional | |
$ (allOf 2).team (anyOf 1) | JSON | Alternative | |
$ (allOf 2).team (anyOf 1) (allOf 1) | Model | All variants apply | Expand Add a user to a team — response body — data data team — Team Compact |
$ (allOf 2).team (anyOf 1) (allOf 2) | object | All variants apply | *Conditional*. This property is only present when the `workspace` provided is an organization. |
$ (allOf 2).team (anyOf 2) | null | Alternative | |
$ (allOf 2).workspace | JSON | Optional | |
$ (allOf 2).workspace (allOf 1) | Model | All variants apply | Expand Update a workspace — request body — body data |
$ (allOf 2).workspace (allOf 2) | object | All variants apply | |
$ (allOf 2).followers | array | Optional | Array of users who are members of this goal. |
$ (allOf 2).followers[] | Model | Each item | Expand Get users in a team — response body — data data item |
$ (allOf 2).time_period | JSON | Optional | |
$ (allOf 2).time_period (anyOf 1) | JSON | Alternative | |
$ (allOf 2).time_period (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get time periods — response body — data, next page data item |
$ (allOf 2).time_period (anyOf 1) (allOf 2) | object | All variants apply | |
$ (allOf 2).time_period (anyOf 2) | null | Alternative | |
$ (allOf 2).metric | JSON | Optional | |
$ (allOf 2).metric (anyOf 1) | JSON | Alternative | |
$ (allOf 2).metric (anyOf 1) (allOf 1) | Model | All variants apply | Expand 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) | object | All variants apply | |
$ (allOf 2).metric (anyOf 1) (allOf 2).can_manage | boolean | Optional | *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) | null | Alternative | |
$ (allOf 2).owner | JSON | Optional | |
$ (allOf 2).owner (anyOf 1) | JSON | Alternative | |
$ (allOf 2).owner (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get users in a team — response body — data data item |
$ (allOf 2).owner (anyOf 1) (allOf 2) | object | All variants apply | |
$ (allOf 2).owner (anyOf 2) | null | Alternative | |
$ (allOf 2).current_status_update | JSON | Optional | |
$ (allOf 2).current_status_update (anyOf 1) | JSON | Alternative | |
$ (allOf 2).current_status_update (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get status updates from an object — response body — data, next page data item |
$ (allOf 2).current_status_update (anyOf 1) (allOf 2) | JSON | All variants apply | The latest `status_update` posted to this goal. |
$ (allOf 2).current_status_update (anyOf 2) | null | Alternative | |
$ (allOf 2).status | JSON | Optional | |
$ (allOf 2).status (anyOf 1) | string | Alternative | The 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) | null | Alternative | |
$ (allOf 2).privacy_setting | string | Optional | The privacy setting of the goal. Known values: public_to_workspace, members_only |
$ (allOf 2).default_access_level | string | Optional | The default access level when inviting new members to the goal Known values: admin, editor, commenter, viewer |
$ (allOf 2).custom_fields | array | Optional | Array 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[] | Model | Each item | Expand Get a membership — response body — data / data / access_level: admin, editor, user parent |
$ (allOf 2).custom_field_settings | array | Optional | Array 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[] | Model | Each item | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A generic Asana Resource, containing a globally unique identifier. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the goal. |
html_notes | string | Optional | The notes of the goal with formatting as HTML. See [rich text](/docs/rich-text). |
notes | string | Optional | Free-form textual information associated with the goal (i.e. its description). |
due_on | JSON | Optional | |
due_on (anyOf 1) | string | Alternative | The localized day on which this goal is due. This takes a date with format `YYYY-MM-DD`. |
due_on (anyOf 2) | null | Alternative | |
start_on | JSON | Optional | |
start_on (anyOf 1) | string | Alternative | 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. |
start_on (anyOf 2) | null | Alternative | |
is_workspace_level | boolean | Optional | *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. |
liked | boolean | Optional | True if the goal is liked by the authorized user, false if not. |
likes | array | Optional | Array of likes for users who have liked this goal. Read only: true |
likes[] | Model | Each item | Expand Get a goal — response body — data data likes item |
num_likes | JSON | Optional | |
num_likes (anyOf 1) | integer | Alternative | The number of users who have liked this goal. Read only: true |
num_likes (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
team | JSON | Optional | |
team (anyOf 1) | Model | Alternative | Expand Get a goal — response body — data data team gid, name, resource type |
team (anyOf 2) | null | Alternative | |
workspace | Model | Optional | Expand Get a tag — response body — data data workspace |
followers | array | Optional | Array of users who are members of this goal. |
followers[] | Model | Each item | Expand Get an OOO entry — response body — data data user |
time_period | JSON | Optional | |
time_period (anyOf 1) | Model | Alternative | Expand Get a time period — response body — data / data / parent / period: FY, H1, H2, Q1, Q2, Q3, Q4 |
time_period (anyOf 2) | null | Alternative | |
metric | JSON | Optional | |
metric (anyOf 1) | object | Alternative | A generic Asana Resource, containing a globally unique identifier. |
metric (anyOf 1).gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
metric (anyOf 1).resource_type | string | Optional | The base type of this resource. Read only: true |
metric (anyOf 1).resource_subtype | string | Optional | 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. Known values: number Read only: true |
metric (anyOf 1).precision | JSON | Optional | |
metric (anyOf 1).precision (anyOf 1) | integer | Alternative | *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) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
metric (anyOf 1).unit | string | Optional | A supported unit of measure for the goal metric, or none. Known values: none, currency, percentage |
metric (anyOf 1).currency_code | JSON | Optional | |
metric (anyOf 1).currency_code (anyOf 1) | string | Alternative | ISO 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) | null | Alternative | |
metric (anyOf 1).initial_number_value | JSON | Optional | |
metric (anyOf 1).initial_number_value (anyOf 1) | number | Alternative | This number is the start value of a goal metric of type number. |
metric (anyOf 1).initial_number_value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
metric (anyOf 1).target_number_value | JSON | Optional | |
metric (anyOf 1).target_number_value (anyOf 1) | number | Alternative | This 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) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
metric (anyOf 1).current_number_value | JSON | Optional | |
metric (anyOf 1).current_number_value (anyOf 1) | number | Alternative | This number is the current value of a goal metric of type number. |
metric (anyOf 1).current_number_value (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
metric (anyOf 1).current_display_value | string | Optional | This string is the current value of a goal metric of type string. Read only: true |
metric (anyOf 1).progress_source | string | Optional | This 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_weight | boolean | Optional | *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_manage | boolean | Optional | *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) | null | Alternative | |
owner | JSON | Optional | |
owner (anyOf 1) | Model | Alternative | Expand Get an OOO entry — response body — data data user |
owner (anyOf 2) | null | Alternative | |
current_status_update | JSON | Optional | |
current_status_update (anyOf 1) | object | Alternative | 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.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).gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
current_status_update (anyOf 1).resource_type | string | Optional | The base type of this resource. Read only: true |
current_status_update (anyOf 1).title | string | Optional | The title of the status update. |
current_status_update (anyOf 1).resource_subtype | string | Optional | 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`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) | null | Alternative | |
status | JSON | Optional | |
status (anyOf 1) | string | Alternative | The 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) | null | Alternative | |
privacy_setting | string | Optional | The privacy setting of the goal. Known values: public_to_workspace, members_only |
default_access_level | string | Optional | The default access level when inviting new members to the goal Known values: admin, editor, commenter, viewer |
custom_fields | array | Optional | Array 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[] | Model | Each item | Expand Get a goal — response body — data data custom fields item |
custom_field_settings | array | Optional | Array 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[] | Model | Each item | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | |
data[] | Model | Each item | Expand Get a goal — response body — data data — sdk__Goal Response |
next_page | Model | Optional | Expand 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | object | Alternative | *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).offset | string | Optional | Pagination offset for the request. Read only: true |
$ (anyOf 1).path | string | Optional | A relative path containing the query parameters to fetch for next_page Read only: true |
$ (anyOf 1).uri | string | Optional | A full uri containing the query parameters to fetch for next_page Format: uri Read only: true |
$ (anyOf 2) | null | Alternative |
Get parent goals from a goal — response body — data data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A generic Asana Resource, containing a globally unique identifier. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
name | string | Optional | The name of the goal. |
owner | JSON | Optional | |
owner (anyOf 1) | JSON | Alternative | |
owner (anyOf 1) (allOf 1) | Model | All variants apply | Expand Get users in a team — response body — data data item |
owner (anyOf 1) (allOf 2) | object | All variants apply | |
owner (anyOf 2) | null | Alternative |
Referenced models: Get users in a team — response body — data data item
Remove a custom field from a goal — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
custom_field | string | Required within parent | The custom field to remove from this portfolio. |
Update a goal metric — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A generic Asana Resource, containing a globally unique identifier. |
gid | string | Optional | Globally unique identifier of the resource, as a string. Read only: true |
resource_type | string | Optional | The base type of this resource. Read only: true |
current_number_value | number | Optional | *Conditional*. This number is the current value of a goal metric of type number. |
Update a goal — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (allOf 1) | Model | All variants apply | Expand 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) | object | All variants apply | |
$ (allOf 2).status | JSON | Optional | |
$ (allOf 2).status (anyOf 1) | string | Alternative | The 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) | null | Alternative | |
$ (allOf 2).custom_fields | object | Optional | An 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.* | string | Additional 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_fields | object | Optional | An 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.* | string | Additional 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