API query methods

This page is about OKR for Jira Cloud. Using Data Center? Click here.

Base URL for all API calls

If you are in the EU region: https://eu.okr-jira-prod.appfire.com
Everywhere else: https://okr-jira-prod.appfire.com

Key notes

While updates are available via API, using the percentDone field directly on Objectives and Key Results is preferred for progress tracking.
Progress values for manual Key Result updates are not editable and won't be present in the retrieved data.
Objective progress cannot be tracked via updates.

Contents

Contents
1 Base URL for all API calls 2 Key notes 3 Query objectives by date 4 Query objectives by ID 5 Query key results by date 6 Query key results by ID 7 Query updates by entity ID 8 Query comments

Query objectives by date

The query retrieves a list of all objectives that have a start date and/or due date within the specified date range.

GET /api/v2/api-export/objectives/byDate

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`startDateEpochMilli`	Start date of query time window, in UNIX Epoch time format, in milliseconds.
`deadlineEpochMilli`	End date of query time window, in UNIX Epoch time format, in milliseconds.
`expand`	A list of objects you want to include expanded in request. By default, you receive only the IDs of connected entities. Permitted values: KEY_RESULTS,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byDate?
startDateEpochMilli=1409459200000
&deadlineEpochMilli=1748647410000
&expand=KEY_RESULTS,TEAMS,PERIODS,LABELS

curl --request GET \
  --url 'https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byDate?startDateEpochMilli=1600647410000&deadlineEpochMilli=1748647410000&expand=KEY_RESULTS,TEAMS,PERIODS,LABELS' \
  --header 'API-Token: {token}' \
  --header 'Content-Type: application/json'

{
	"okrs": [
		{
			"id": "5fda249d289742000406b3e4",
			"key": "O-2",
			"name": "Become more mature company",
			"link": "https://test-okr-prd.atlassian.net/plugins/servlet/ac/com.digitaltoucan.okrforjira/okrs-general-page#!eyJ0eXBlIjoiT0JKRUNUSVZFIiwib2tySWQiOiI1ZmVhZTJmZGNjYTIyMTAwMDMxNWFiMWYifQ%3D%3D",
			"description": "<p>This quarter we will be focusing on improving our performance.</p><p></p>",
			"parentObjectiveId": null,
			"ownerAccountId": "5c12ad9fd3af3b1ccfecbf55",
			"collaboratorAccountIds": [],
			"percentDone": 8.333333333333332,
			"created": "2020-12-16T15:15:41+0000",
			"startDate": "2021-01-01T00:00:00+0000",
			"deadline": "2021-03-31T23:59:59+0000",
			"labelIds": [],
			"teamIds": [],
			"krIds": [
				"605480b190c42b0003385170",
				"6061e921e2f4470003bc3210"
			],
			"childObjectiveIds": [
				"5fdb72c63d2cf000035ceb37",
				"60743135b347480003dc6a9c",
				"61f9367df9aa7f0e4024a6fe"
			],
			"latestUpdate": {
				"entityId": "5fda249d289742000406b3e4",
				"status": "ON_TRACK",
				"created": "2021-05-05T12:15:14+0000",
				"value": null,
				"description": ""
			},
			"periodAliasId": "602a6a2717378700039f342a",
			"weight": 0
		}
	],
	"krs": [
		{
			"id": "605480b190c42b0003385170",
			"key": "KR-8",
			"name": "new auto KR",
			"link": "https://test-okr-prd.atlassian.net/plugins/servlet/ac/com.digitaltoucan.okrforjira/okrs-general-page#!eyJ0eXBlIjoiS1IiLCJrcklkIjoiNjExYTFhMjljMzg1Zjg1YzEzYWM4NjI0In0%3D",
			"description": null,
			"parentObjectiveId": "5fda249d289742000406b3e4",
			"issueIds": [
				"10005",
				"10006",
				"10010"
			],
			"ownerAccountId": "5dbfee8570f1ea0df7698353",
			"collaboratorAccountIds": [
				"5c12ad9fd3af3b1ccfecbf55"
			],
			"percentDone": 33.33333333333333,
			"created": "2021-03-19T10:45:05+0000",
			"startDate": "2021-01-01T00:00:00+0000",
			"deadline": "2021-03-31T23:59:59+0000",
			"labelIds": [],
			"teamIds": [],
			"periodAliasId": "602a6a2717378700039f342a",
			"latestUpdate": {
				"entityId": "620ea538512edb00acf67ac1",
				"status": "ON_TRACK",
				"created": "2022-02-17T19:42:43+0000",
				"value": 1.0,
				"description": null
			},
			"unit": null,
			"currentProgressDefinition": {
				"type": "AUTO",
				"startValue": null,
				"desiredValue": null,
				"jql": "project= TEST"
			},
			"weight": 1
		},
		{
			"id": "6061e921e2f4470003bc3210",
			"key": "KR-9",
			"name": "different start date",
			"link": "https://test-okr-prd.atlassian.net/plugins/servlet/ac/com.digitaltoucan.okrforjira/okrs-general-page#!eyJ0eXBlIjoiS1IiLCJrcklkIjoiNjExYTFhMjljMzg1Zjg1YzEzYWM4NjI0In0%3D",
			"description": null,
			"parentObjectiveId": "5fda249d289742000406b3e4",
			"issueIds": [
				"10000"
			],
			"ownerAccountId": "5dbfee8570f1ea0df7698353",
			"collaboratorAccountIds": [],
			"percentDone": 0.0,
			"created": "2021-03-29T14:50:09+0000",
			"startDate": "2020-04-01T00:00:00+0000",
			"deadline": "2020-06-30T23:59:59+0000",
			"labelIds": [],
			"teamIds": [],
			"periodAliasId": null,
			"latestUpdate": {
				"entityId": "61138f2be5fd454858c3e1ee",
				"status": "AT_RISK",
				"created": "2021-08-11T08:49:47+0000",
				"value": 0.0,
				"description": null
			},
			"unit": {
				"name": "USD",
				"symbol": "$"
			},
			"currentProgressDefinition": {
				"type": "STANDARD",
				"startValue": 0.0,
				"desiredValue": 1.0,
				"jql": null
			},
			"weight": 1
		}
	],
	"teams": [],
	"periods": [
		{
			"id": "602a6a2717378700039f342a",
			"name": "Q1 Y2021",
			"startDate": "2021-01-01T00:00:00+0000",
			"deadline": "2021-03-31T23:59:59+0000"
		}
	],
	"labels": []
}

Query objectives by ID

The query for a list of all objectives with specified IDs.

GET /api/v2/api-export/objectives/byIds

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`objectiveIds`	Comma separated list of objective IDs you want to receive.
`expand`	A list of objects you want to include expanded in reqeust. By default, you receive only the IDs of connected entities. Permitted values: KEY_RESULTS,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byIds?objectiveIds=5fda249d289742000406b3e4
&expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS

curl --request GET \
  --url 'https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byIds?expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS&objectiveIds=5fda249d289742000406b3e4,5fdb72c63d2cf000035ceb37' \
  --header 'API-Token: {token}' \
  --header 'Content-Type: application/json'

Query key results by date

The query retrieves a list of all key results that have a start date and/or due date within the specified date range.

GET /api/v2/api-export/keyResults/byDate

Parameter	Description	Mandatory

Parameter

Description

Mandatory

startDateEpochMilli

Start date of query time window, in UNIX Epoch time format, in milliseconds.

deadlineEpochMilli

End date of query time window, in UNIX Epoch time format, in milliseconds.

expand

A list of objects you want to include expanded in reqeust. By default, you receive only the IDs of connected entities.

Permitted values: OBJECTIVES,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/keyResults/byDate?
startDateEpochMilli=1509459200000
&deadlineEpochMilli=1748647410000
&expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS

Query key results by ID

Query for a list of all key results with specified IDs.

GET /api/v2/api-export/keyResults/byIds

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`keyResultIds`	Comma separated list of key result ids you want to receive.
`expand`	A list of objects you want to include expanded in reqeust. By default, you receive only the IDs of connected entities. Permitted values: KEY_RESULTS,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/keyResults/byIds?
expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS
&keyResultIds=5fda249d289742000406b3e5

Query updates by entity ID

This query retrieves updates for objectives or key results, displaying the newest ones first.

NOTE ON PROGRESS: Updates are not the best way to calculate progress. Utilize the percentDone field on Objectives and Key Results to obtain the latest progress value.

Updates for non-auto Key Results have startValue, value, and desiredValue fields. They allow tracking changes in the progress of a Key Result. The latest update for a Key Result will have an up-to-date value.

As for auto KR updates, there are two kinds of them. Automatic updates are generated when connected issues change status, and such updates have progress values. You can also create a manual update with a description, but progress values are not editable and will not be present on the Update object fetched through API.

Objective progress cannot be traced by its updates. Objective updates will always have their progress as null. We calculate the progress of an objective in-flight and do not generate an update for every change in the Objective's underlying Key Results.

GET /api/v2/api-export/updates

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`entityId`	ID of a single objective or key result to return updates for. If no ID is provided, updates for all key results and objectives will be returned, newest first.
`earlierThan`	Only updates earlier than the date provided will be returned. Should be provided in UNIX Epoch time format, in milliseconds.
`cursor`	This endopint supports cursor-based pagination. Request returns up to `pageSize` records. If there are more updates, than fit in current page, `nextCursor` field would be populated in response object. You can get next page of updates by using value of `nextCursor` as `cursor` parameter in next request. Lack of `nextCursor` means there are no more updates to return.
`pageSize`	Controls how many updates the request will return in single response. If there are more updates than returned, `nextCursor` field of response object will be populated. Takes values from 1 to 1000. Default value is 1000.

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/updates?entityId=5fda249d289742000406b3e5&pageSize=100&cursor=MTY0MDYwMDQ5MDI5MA==

Query comments

Query paged comments (all or for given updateIds).

GET /api/v2/api-export/updateComments

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`updateId`	Ids of updates to retrieve comments. If no ids provided, comments for all updates will be returned, newest first.
`cursor`	This endopint supports cursor-based pagination. Request returns up to `pageSize` records. If there are more updates, than fit in current page, `nextCursor` field would be populated in response object. You can get next page of comments by using value of `nextCursor` as `cursor` parameter in next request. Lack of `nextCursor` means there are no more comments to return.
`pageSize`	Controls how many comments the request will return in single response. If there are more comments than returned, `nextCursor` field of response object will be populated. Takes values from 1 to 1000. Default value is 1000.

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/updateComments?updateId=6453c760a3b1a006776f1c7f&pageSize=1&cursor=MTY4MzIxMjE0MTA1OQ==