How to: Query Planned, Target and Velocity datapoints in Agility

Question

How do I query Planned, Target, and Velocity datapoints in the backend for the Planned Number (i.e. the number alongside the padlock in the Iteration/Sprint Planning screen)?

Answer

Planned

To query for the Planned Estimate of a Sprint/Iteration (as an example)

<Server Base URI>rest-1.v1/Data/Timebox/2400?sel=Workitems:PrimaryWorkitem[AssetState!="Dead";
   Scope=$ScopeContext;Team=$Team].Estimate.@Sum&asof=2020-03-09T00:00:00&with=$Scope=Scope:1071

Target

Target Estimate value on the Iteration Scheduling page; this value is the "TargetEstimate" value for the Iteration (Timebox). 

To query for Target Estimate of a Sprint/Iteration (as an example)

<Server Base URI>/rest-1.v1/Data/Timebox?sel=TargetEstimate

Velocity

Average Velocities on Iteration Scheduling Page.

This computation is more complicated as it filters the PrimaryWorkitems by their inclusion in the scope and their exclusion in the scope. If the team selected has work completed within the set of iterations (Timeboxes) outside of the set of selected Planning Levels (Scopes), the page will display two values the velocity in context and the velocity out of context.

This velocity is computed by pulling the sum of the completed PrimaryWorkitems across all Timeboxes in the same Schedule as the Timebox selected that are assigned to the filtered Team, and are either in selected Scopes or not in the selected Scopes.

• Scopes will be the array of scope OIDS of the form, Scope:XXXX
• Team will be the string for the team OID of the form, Team:XXXX
• Schedule will be the string for the schedule OID of the form Schedule:XXXX
  BeginDate is the string date form like 10/20/2021 for the begin date of the first timebox to be included
• EndDate is the string date form like 10/20/2021 for the end date of the last timebox to be included

query.v1 version
{
"from":"Timebox",
"select": ["Workitems:PrimaryWorkitem[EffectiveAssetState='Closed';Scope=$Scope;Team=$Team]
   .Estimate.@Sum","Workitems:PrimaryWorkitem[EffectiveAssetState='Closed';Scope!=$Scope;Team=
   $Team].Estimate.@Sum"],
"filter": ["
"Schedule=$Schedule;BeginDate>=$BeginDate;EndDate<=$EndDate"],
"with": {
    "$Scope": scopes,
    "$Team": team,
    "$Schedule": schedule,
    "$BeginDate": beginDate,
    "$EndDate": endDate
},
"sort": {
     "+BeginDate"
}
}

We then average the two different PrimaryWorkitem estimate sum selections from all the selected timeboxes to display the in-context and out-of-context velocity values.