Editing key results for a goal

You can manage key results using the keyResultItems goal parameter.

See For more information, see:

Add or update key results

To add or update the list of key results for a goal, use theUpdating an entity request. In the request body, pass a fields object with a nested keyResultItems array. See Additional entity parameters for details.

Parameters of objects in the keyResultItems array

Parameter	Description	Data type
type	Method for tracking key result progress: `value`: Based on the specific value. `binary`: Based on whether the key result was achieved. Required parameter	String
text	Text of a key result. Required parameter	String
assignee	User ID or username of the key result owner	Number or string
deadline	Deadline for a key result	Object
progress	Quantitative metrics for progress. Required if progress is tracked by `value`	Object
achieved	Indicates whether the key result was achieved (`binary`). Acceptable values: `true`, `false`	Boolean

deadline object parameters

Parameter	Description	Data type
date	Deadline date in `YYYY-MM-DD` format. Required parameter	String
deadlineType	For key results, the deadline type is set as `date`. Required parameter	String

progress object parameters

Parameter	Description	Data type
start	Initial metric value. Required parameter	Number
end	Final metric value. Required parameter	Number
current	Current metric value	Number

Example 1: Add a list of two key results to a goal. If the goal already has key results, they'll be replaced with the new ones.

PATCH /v3/entities/goal/655f328********?fields=keyResultItems
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
 "fields": {
   "keyResultItems": [
      {
        "type": "value",
        "text": "Key result 1",
        "assignee": "username1",
        "deadline": {"date": "2025-06-03", "deadlineType": "date"},
        "progress": {
            "start": 1,
            "end": 10,
            "current": 5
        }
      },
      {
        "type": "binary",
        "text": "Key result 2",
        "assignee": "username2",
        "deadline": {"date": "2025-06-03", "deadlineType": "date"},
        "achieved": false
      }
   ]
 }
}

Example 2: Add an item to the list of key results.

PATCH /v3/entities/goal/655f328********?fields=keyResultItems
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
 "fields": {
   "keyResultItems": {
     "add": {
       "type": "binary",
       "text": "Key result 3",
       "assignee": "username1"
     }
   }
 }
}

Get key results for a goal

To get the list of key results for a goal, send the Getting entity parameters request with the fields=keyResultItems parameter.

GET https://api.tracker.yandex.net/v3/entities/goal/<goal_id>?fields=keyResultItems

For descriptions of parameters in the keyResultItems array, see Additional entity parameters.

Removing key results

To remove key results, use the Updating an entity request:

To remove all key results from a goal, pass the value "keyResultItems": null.
To remove one or more key results, update the list (see Add or update key results) or use the remove operator.

Example 1. Remove all key results from a goal.

PATCH /v3/entities/goal/655f328********?fields=keyResultItems
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
 "fields": {
       "keyResultItems": null
   }
}

Example 2. Removing a specific key result from the list.

PATCH /v3/entities/goal/655f328********?fields=keyResultItems
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
  "fields": {
     "keyResultItems": {
         "remove": {
             "id": "6789*******",
             "type": "binary",
             "text": "My key result",
             "assignee": {
                 "self": "https://api.tracker.yandex.net/v3/users/11********",
                 "id": "11********",
                 "display": "User Name",
                 "cloudUid": "ajevuhegoggf********",
                 "passportUid": 11********
             }
         }
     }
  }
}

To delete a specific key result from the list, pass an object with the item's parameters in the same format as returned by the Getting entity parameters request.

Was the article helpful?

Deleting one item

Metrics