Asana API
Getting access, Developing, Testing
Back to Asana
Update A Goal Metric
Updates a goal's existing metric's current_number_value if one exists,
otherwise responds with a 400 status code.
Returns the complete updated goal metric record.
Input
type: object
properties:
parameters:
type: object
properties:
goal_gid:
type: string
description: Globally unique identifier for the goal.
opt_pretty:
type: boolean
description: >-
Provides “pretty” output.
Provides the response in a “pretty” format. In the case of JSON this
means doing proper line breaking and indentation to make it readable.
This will take extra time and increase the response size so it is
advisable only to use this during debugging.
opt_fields:
type: array
items:
type: string
description: >-
Defines fields to return.
Some requests return *compact* representations of objects in order to
conserve resources and complete the request more efficiently. Other
times requests return more information than you may need. This option
allows you to list the exact set of fields that the API should be sure
to return for the objects. The field names should be provided as
paths, described below.
The id of included objects will always be returned, regardless of the
field options.
required:
- goal_gid
title: Parameters
data:
type: object
properties:
data:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
current_number_value:
description: >-
*Conditional*. This number is the current value of a goal metric
of type number.
type: number
example: 8.12
title: Data
Output
type: object
properties:
data:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: The name of the goal.
example: Grow web traffic by 30%
html_notes:
type: string
description: The notes of the goal with formatting as HTML.
example: <body>Start building brand awareness.</body>
notes:
type: string
description: >-
Free-form textual information associated with the goal (i.e. its
description).
example: Start building brand awareness.
due_on:
type: string
description: >-
The localized day on which this goal is due. This takes a date with
format `YYYY-MM-DD`.
example: '2019-09-15T00:00:00.000Z'
nullable: true
start_on:
type: string
description: >-
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.
example: '2019-09-14T00:00:00.000Z'
nullable: true
status:
type: string
description: >-
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.
example: green
nullable: true
is_workspace_level:
type: boolean
description: >-
*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.
example: true
liked:
type: boolean
description: True if the goal is liked by the authorized user, false if not.
example: false
likes:
description: Array of likes for users who have liked this goal.
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the object, as a string.
type: string
readOnly: true
example: '12345'
user:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: >-
*Read-only except when same user as requester*. The user’s
name.
example: Greg Sanchez
num_likes:
description: The number of users who have liked this goal.
type: integer
readOnly: true
example: 5
team:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the team.
type: string
example: Marketing
workspace:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the workspace.
type: string
example: My Company Workspace
followers:
type: array
description: Array of users who are members of this goal.
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
time_period:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
end_on:
type: string
description: The localized end date of the time period in `YYYY-MM-DD` format.
example: '2019-09-14T00:00:00.000Z'
start_on:
type: string
description: >-
The localized start date of the time period in `YYYY-MM-DD`
format.
example: '2019-09-13T00:00:00.000Z'
period:
type: string
description: >-
The cadence and index of the time period. The value is one of:
`FY`, `H1`, `H2`, `Q1`, `Q2`, `Q3`, or `Q4`.
enum:
- FY
- H1
- H2
- Q1
- Q2
- Q3
- Q4
example: Q1
display_name:
type: string
description: A string representing the cadence code and the fiscal year.
example: Q1 FY22
metric:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
resource_subtype:
description: >-
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.
type: string
readOnly: true
example: number
enum:
- number
precision:
description: >-
*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%.
type: integer
example: 2
unit:
description: A supported unit of measure for the goal metric, or none.
type: string
enum:
- none
- currency
- percentage
currency_code:
description: >-
ISO 4217 currency code to format this custom field. This will be
null if the `unit` is not `currency`.
type: string
nullable: true
example: EUR
initial_number_value:
description: This number is the start value of a goal metric of type number.
type: number
example: 5.2
target_number_value:
description: >-
This number is the end value of a goal metric of type number. This
number cannot equal `initial_number_value`.
type: number
example: 10.2
current_number_value:
description: This number is the current value of a goal metric of type number.
type: number
example: 8.12
current_display_value:
description: This string is the current value of a goal metric of type string.
type: string
readOnly: true
example: '8.12'
progress_source:
description: >-
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 or
projects, or managed by an integration with an external data
source, such as Salesforce.
type: string
enum:
- manual
- subgoal_progress
- project_task_completion
- project_milestone_completion
- external
example: manual
can_manage:
description: >-
*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.
type: boolean
readOnly: true
example: true
owner:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
current_status_update:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
title:
description: The title of the status update.
type: string
example: Status Update - Jun 15
resource_subtype:
type: string
description: >-
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.
enum:
- project_status_update
- portfolio_status_update
- goal_status_update
example: project_status_update
readOnly: true