Goals

A goal is an object in the goal-tracking system that helps your organization drive measurable results.


GoalCompact

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

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
namestringThe name of the goal.
ownerobject¦nullA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
owner.gidstringGlobally unique identifier of the resource, as a string.
owner.resource_typestringThe base type of this resource.
owner.namestringRead-only except when same user as requester. The user’s name.
{
  "gid": "12345",
  "resource_type": "goal",
  "name": "Grow web traffic by 30%",
  "owner": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  }
}

Goal

PropertyTypeDescription
gidstringGlobally unique identifier of the resource, as a string.
resource_typestringThe base type of this resource.
due_onstring¦nullThe localized day on which this goal is due. This takes a date with format YYYY-MM-DD.
html_notesstringThe notes of the goal with formatting as HTML.
is_workspace_levelbooleanConditional. 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.
likedbooleanTrue if the goal is liked by the authorized user, false if not.
namestringThe name of the goal.
notesstringFree-form textual information associated with the goal (i.e. its description).
start_onstring¦nullThe day on which work for this goal begins, or null if the goal has no start date. This takes a date with YYYY-MM-DD format, and cannot be set unless there is an accompanying due date.
statusstring¦nullThe 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 that you can only write to this property if metric is set.
current_status_updateobjectA 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 project.
current_status_update.gidstringGlobally unique identifier of the resource, as a string.
current_status_update.resource_typestringThe base type of this resource.
current_status_update.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.

The resource_subtypes for status objects represent the type of their parent.
current_status_update.titlestringThe title of the status update.
followers[object]Array of users who are members of this goal.
» {}.gidstringGlobally unique identifier of the resource, as a string.
» {}.resource_typestringThe base type of this resource.
» {}.namestringRead-only except when same user as requester. The user’s name.
likes[object]Array of likes for users who have liked this goal.
» {}.gidstringGlobally unique identifier of the object, as a string.
» {}.userobjectA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
» {}.user.gidstringGlobally unique identifier of the resource, as a string.
» {}.user.resource_typestringThe base type of this resource.
» {}.user.namestringRead-only except when same user as requester. The user’s name.
metricobject¦nullA generic Asana Resource, containing a globally unique identifier.
metric.gidstringGlobally unique identifier of the resource, as a string.
metric.resource_typestringThe base type of this resource.
metric.currency_codestring¦nullISO 4217 currency code to format this custom field. This will be null if the unit is not currency.
metric.current_display_valuestringThis string is the current value of a goal metric of type string.
metric.current_number_valuenumberThis number is the current value of a goal metric of type number.
metric.initial_number_valuenumberThis number is the start value of a goal metric of type number.
metric.precisionintegerConditional. 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.progress_sourcestringThis 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.
metric.resource_subtypestringThe subtype of this resource. Different subtypes retain many of the same fields and behavior, but may render differently in Asana or represent resources with different semantic meaning.
metric.target_number_valuenumberThis number is the end value of a goal metric of type number. This number cannot equal initial_number_value.
metric.unitstringA supported unit of measure for the goal metric, or none.
metric.can_managebooleanConditional. 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.
metric.is_custom_weightbooleanConditional. 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
num_likesintegerThe number of users who have liked this goal.
ownerobject¦nullA user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
owner.gidstringGlobally unique identifier of the resource, as a string.
owner.resource_typestringThe base type of this resource.
owner.namestringRead-only except when same user as requester. The user’s name.
teamobject¦nullA team is used to group related projects and people together within an organization. Each project in an organization is associated with a team.
team.gidstringGlobally unique identifier of the resource, as a string.
team.resource_typestringThe base type of this resource.
team.namestringThe name of the team.
time_periodobject¦nullA generic Asana Resource, containing a globally unique identifier.
time_period.gidstringGlobally unique identifier of the resource, as a string.
time_period.resource_typestringThe base type of this resource.
time_period.display_namestringA string representing the cadence code and the fiscal year.
time_period.end_onstringThe localized end date of the time period in YYYY-MM-DD format.
time_period.periodstringThe cadence and index of the time period. The value is one of: FY, H1, H2, Q1, Q2, Q3, or Q4.
time_period.start_onstringThe localized start date of the time period in YYYY-MM-DD format.
workspaceobjectA workspace is the highest-level organizational unit in Asana. All projects and tasks have an associated workspace.
workspace.gidstringGlobally unique identifier of the resource, as a string.
workspace.resource_typestringThe base type of this resource.
workspace.namestringThe name of the workspace.
{
  "gid": "12345",
  "resource_type": "goal",
  "due_on": "2019-09-15",
  "html_notes": "<body>Start building brand awareness.</body>",
  "is_workspace_level": true,
  "liked": false,
  "name": "Grow web traffic by 30%",
  "notes": "Start building brand awareness.",
  "start_on": "2019-09-14",
  "status": "green",
  "current_status_update": {
    "gid": "12345",
    "resource_type": "status_update",
    "resource_subtype": "project_status_update",
    "title": "Status Update - Jun 15"
  },
  "followers": [
    {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    }
  ],
  "likes": [
    {
      "gid": "12345",
      "user": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    }
  ],
  "metric": {
    "gid": "12345",
    "resource_type": "task",
    "currency_code": "EUR",
    "current_display_value": "8.12",
    "current_number_value": 8.12,
    "initial_number_value": 5.2,
    "precision": 2,
    "progress_source": "manual",
    "resource_subtype": "number",
    "target_number_value": 10.2,
    "unit": "none",
    "can_manage": true
  },
  "num_likes": 5,
  "owner": {
    "gid": "12345",
    "resource_type": "user",
    "name": "Greg Sanchez"
  },
  "team": {
    "gid": "12345",
    "resource_type": "team",
    "name": "Marketing"
  },
  "time_period": {
    "gid": "12345",
    "resource_type": "time_period",
    "display_name": "Q1 FY22",
    "end_on": "2019-09-14",
    "period": "Q1",
    "start_on": "2019-09-13"
  },
  "workspace": {
    "gid": "12345",
    "resource_type": "workspace",
    "name": "My Company Workspace"
  }
}