🚀 Heads up: Our API Docs Have Moved!
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.

Outcome Results API

API for accessing learning outcome results

An OutcomeResult object looks like:

// A student's result for an outcome
{
  // A unique identifier for this result
  "id": 42,
  // The student's score
  "score": 6,
  // The datetime the resulting OutcomeResult was submitted at, or absent that,
  // when it was assessed.
  "submitted_or_assessed_at": "2013-02-01T00:00:00-06:00",
  // Unique identifiers of objects associated with this result
  "links": {"user":"3","learning_outcome":"97","alignment":"53"},
  // score's percent of maximum points possible for outcome, scaled to reflect any
  // custom mastery levels that differ from the learning outcome
  "percent": 0.65
}

An OutcomeRollupScoreLinks object looks like:

{
  // The id of the related outcome
  "outcome": 42
}

An OutcomeRollupScore object looks like:

{
  // The rollup score for the outcome, based on the student alignment scores
  // related to the outcome. This could be null if the student has no related
  // scores.
  "score": 3,
  // The number of alignment scores included in this rollup.
  "count": 6,
  "links": {"outcome":"42"}
}

An OutcomeRollupLinks object looks like:

{
  // If an aggregate result was requested, the course field will be present.
  // Otherwise, the user and section field will be present (Optional) The id of
  // the course that this rollup applies to
  "course": 42,
  // (Optional) The id of the user that this rollup applies to
  "user": 42,
  // (Optional) The id of the section the user is in
  "section": 57
}

An OutcomeRollup object looks like:

{
  // an array of OutcomeRollupScore objects
  "scores": null,
  // The name of the resource for this rollup. For example, the user name.
  "name": "John Doe",
  "links": {"course":42,"user":42,"section":57}
}

An OutcomeAlignment object looks like:

// An asset aligned with this outcome
{
  // A unique identifier for this alignment
  "id": "quiz_3",
  // The name of this alignment
  "name": "Big mid-term test",
  // (Optional) A URL for details about this alignment
  "html_url": null
}

An OutcomePath object looks like:

// The full path to an outcome
{
  // A unique identifier for this outcome
  "id": 42,
  // an array of OutcomePathPart objects
  "parts": null
}

An OutcomePathPart object looks like:

// An outcome or outcome group
{
  // The title of the outcome or outcome group
  "name": "Spelling out numbers"
}

Get outcome results OutcomeResultsController#index

GET /api/v1/courses/:course_id/outcome_results

Scope: url:GET|/api/v1/courses/:course_id/outcome_results

Gets the outcome results for users and outcomes in the specified context. used in sLMGB

Request Parameters:

Parameter	Type	Description
user_ids[]	integer	If specified, only the users whose ids are given will be included in the results. SIS ids can be used, prefixed by "sis_user_id:". It is an error to specify an id for a user who is not a student in the context.
outcome_ids[]	integer	If specified, only the outcomes whose ids are given will be included in the results. it is an error to specify an id for an outcome which is not linked to the context.
include[]	string	[String, "alignments"\|"outcomes"\|"outcomes.alignments"\|"outcome_groups"\|"outcome_links"\|"outcome_paths"\|"users"] Specify additional collections to be side loaded with the result. "alignments" includes only the alignments referenced by the returned results. "outcomes.alignments" includes all alignments referenced by outcomes in the context.
include_hidden	boolean	If true, results that are hidden from the learning mastery gradebook and student rollup scores will be included

Example Response:

{
  outcome_results: [OutcomeResult]
}

Set outcome ordering for LMGB OutcomeResultsController#outcome_order

POST /api/v1/courses/:course_id/assign_outcome_order

Scope: url:POST|/api/v1/courses/:course_id/assign_outcome_order

Saves the ordering of outcomes in LMGB for a user

Get outcome result rollups OutcomeResultsController#rollups

GET /api/v1/courses/:course_id/outcome_rollups

Scope: url:GET|/api/v1/courses/:course_id/outcome_rollups

Gets the outcome rollups for the users and outcomes in the specified context.

Request Parameters:

Parameter	Type	Description
aggregate	string	If specified, instead of returning one rollup for each user, all the user rollups will be combined into one rollup for the course that will contain the average (or median, see below) rollup score for each outcome. Allowed values: `course`
aggregate_stat	string	If aggregate rollups requested, then this value determines what statistic is used for the aggregate. Defaults to "mean" if this value is not specified. Allowed values: `mean`, `median`
user_ids[]	integer	If specified, only the users whose ids are given will be included in the results or used in an aggregate result. it is an error to specify an id for a user who is not a student in the context
outcome_ids[]	integer	If specified, only the outcomes whose ids are given will be included in the results. it is an error to specify an id for an outcome which is not linked to the context.
include[]	string	[String, "courses"\|"outcomes"\|"outcomes.alignments"\|"outcome_groups"\|"outcome_links"\|"outcome_paths"\|"users"] Specify additional collections to be side loaded with the result.
exclude[]	string	Specify additional values to exclude. "missing_user_rollups" excludes rollups for users without results. "missing_outcome_results" excludes outcomes without results. Allowed values: `missing_user_rollups`, `missing_outcome_results`,
sort_by	string	If specified, sorts outcome result rollups. "student" sorting will sort by a user's sortable name. "outcome" sorting will sort by the given outcome's rollup score. The latter requires specifying the "sort_outcome_id" parameter. By default, the sort order is ascending. Allowed values: `student`, `outcome`
sort_outcome_id	integer	If outcome sorting requested, then this determines which outcome to use for rollup score sorting.
sort_order	string	If sorting requested, then this allows changing the default sort order of ascending to descending. Allowed values: `asc`, `desc`
add_defaults	boolean	If defaults are requested, then color and mastery level defaults will be added to outcome ratings in the rollup. This will only take effect if the Account Level Mastery Scales FF is DISABLED
contributing_scores	boolean	DEPRECATED: This parameter is deprecated. Use the separate GET /api/v1/courses/:course_id/outcomes/:outcome_id/contributing_scores endpoint instead to fetch contributing scores for a specific outcome. If contributing scores are requested, then each individual outcome score will also include all graded artifacts that contributed to the outcome score

Example Response:

{
  "rollups": [OutcomeRollup],
  "linked": {
    // (Optional) Included if include[] has outcomes
    "outcomes": [Outcome],

    // (Optional) Included if aggregate is not set and include[] has users
    "users": [User],

    // (Optional) Included if aggregate is 'course' and include[] has courses
    "courses": [Course]

    // (Optional) Included if include[] has outcome_groups
    "outcome_groups": [OutcomeGroup],

    // (Optional) Included if include[] has outcome_links
    "outcome_links": [OutcomeLink]

    // (Optional) Included if include[] has outcome_paths
    "outcome_paths": [OutcomePath]

    // (Optional) Included if include[] has outcomes.alignments
    "outcomes.alignments": [OutcomeAlignment]
  }
}

Get contributing scores OutcomeResultsController#contributing_scores

GET /api/v1/courses/:course_id/outcomes/:outcome_id/contributing_scores

Scope: url:GET|/api/v1/courses/:course_id/outcomes/:outcome_id/contributing_scores

Gets the contributing scores for a specific outcome and set of users. Contributing scores are the individual assignment/quiz scores that contributed to the outcome score for each user. Returns all alignments for the outcome in the course context.

Request Parameters:

Parameter	Type	Description
user_ids[]	integer	If specified, only the users whose ids are given will be included in the results. It is an error to specify an id for a user who is not a student in the context.
only_assignment_alignments	boolean	If specified, only assignment alignments will be included in the results.
show_unpublished_assignments	boolean	If true, unpublished assignments will be included in the results. Defaults to false.

Example Response:

{
  "outcome": {
    "id": "1",
    "title": "Outcome 1"
  },
  "alignments": [
    {
      "alignment_id": "123",
      "associated_asset_id": "456",
      "associated_asset_name": "Assignment 1",
      "associated_asset_type": "Assignment"
    }
  ],
  "scores": [
    {
      "user_id": "1",
      "alignment_id": "123",
      "score": 3.5
    }
  ]
}

Get mastery distribution OutcomeResultsController#mastery_distribution

GET /api/v1/courses/:course_id/outcome_mastery_distribution

Scope: url:GET|/api/v1/courses/:course_id/outcome_mastery_distribution

Returns the distribution of student scores across mastery levels for all outcomes. This endpoint fetches data for ALL students (not paginated) to provide accurate distribution statistics for charts and analytics.

Request Parameters:

Parameter	Type	Description
exclude[]	string	Optionally restrict which results are included: - "missing_user_rollups": exclude students without any scores - "missing_outcome_results": exclude outcomes without any results
outcome_ids[]	string	Optionally restrict to specific outcome IDs
student_ids[]	string	Optionally restrict to specific student IDs. If not provided, all students will be included.
include[]	string	Optionally include additional data: - "alignment_distributions": include contributing score distributions for alignments
only_assignment_alignments	boolean	If true and alignment_distributions is included, only include assignment alignments. Default: false.
show_unpublished_assignments	boolean	If true, include unpublished assignments in alignment distributions. Default: false.
add_defaults	boolean	If defaults are requested, then color and mastery level defaults will be added to outcome ratings in the result. This will only take effect if the Account Level Mastery Scales FF is DISABLED

Example Response:

{
  "outcome_distributions": {
    "1": {
      "outcome_id": "1",
      "ratings": [
        {
          "description": "Exceeds Mastery",
          "points": 4.0,
          "color": "#127A1B",
          "count": 5,
          "student_ids": ["1", "3", "7", "12", "15"]
        },
        {
          "description": "Mastery",
          "points": 3.0,
          "color": "#0B874B",
          "count": 12,
          "student_ids": ["2", "4", "5", ...]
        }
      ],
      "total_students": 28,
      "alignment_distributions": {
        "content_tag_123": {
          "alignment_id": "content_tag_123",
          "ratings": [
            {
              "description": "Exceeds Mastery",
              "points": 4.0,
              "color": "#127A1B",
              "count": 3,
              "student_ids": ["1", "7", "12"]
            }
          ],
          "total_students": 28
        }
      }
    }
  },
  "students": [
    {
      "id": "1",
      "name": "Student Name",
      "sortable_name": "Name, Student"
    }
  ]
}

Enqueue a delayed Outcome Rollup Calculation Job OutcomeResultsController#enqueue_outcome_rollup_calculation

POST /api/v1/enqueue_outcome_rollup_calculation

Scope: url:POST|/api/v1/enqueue_outcome_rollup_calculation