Get Line Items
The LTI® protocol allows you to retrieve grade lines from the LMS grade book through the Assignment and Grades - Line Items service. In the context of LTI®, these grade lines are called line items. LTIAAS gives you access to this service through the /api/lineitems API endpoint.
Please check our Manipulating grade lines guide and its Retrieving grade lines section to learn more about using this endpoint.
| API Authentication Method | Supported |
|---|---|
LTIK-AUTH-V2 | ✅ |
SERVICE-AUTH-V1 | ✅ |
Bearer |
Query Parameters
Filters line items by the resource link ID attached to the current launch context
Filters line items by resourceId
Filters line items by tag
Possible values: >= 1
Limits the number of line items returned. the platform MAY further reduce the number of items returned at its own discretion.
Retrieves line items from a specific URL. - When present, the url parameter causes every other parameter to be ignored. - The url parameter should be URL encoded. - In cases where not all line items are retrieved when the line item limit is reached, the returned object will contain a next field holding an URL that can be used to retrieve the remaining line items through the url parameter.
- 200
- 401
Schema
- Array [
- ]
lineItems object[] required
An array of line items.
URL uniquely identifying the result record.
The label is a short string with a human readable text for the line item. It MUST be specified and not blank when posted by the tool. A platform must always include the label.
Possible values: > 0
The maximum score for this line item. Maximum score MUST be a numeric non-null value, strictly greater than 0.
A line item MAY be attached to a resource link by including a 'resourceLinkId' in the payload. The resource link MUST exist in the context where the line item is created, and MUST be a link owned by the same tool. If not, the line item creation MUST fail with a response code of Not Found 404.
The platform MAY remove the line items attached to a resource link if the resource link itself is removed.
A tool MAY identify to which of its resources the line item is attached to by including a non blank value for resourceId in the payload. This value is a string. For example, resourceId can be 'quiz-231' or any other resource identifier uniquely identifying a resource in a given context.
Multiple line items can share the same resourceId within a given context. resourceId must be preserved when a context is copied if the line items are included in the copy.
If no resourceId is defined for a lineitem, the platform may omit this attribute, or include it with a blank or null value.
A tool MAY further qualify a line item by setting a value to tag. The attribute is a string. For example, one assignment resource may have 2 line items, one with tag as 'grade' and the other tagged as 'originality'.
Multiple line items can share the same tag within a given context. tag must be preserved when a context is copied if the line items are included in the copy.
If no tag is defined for a lineitem, the platform may omit this attribute, or include it with a blank or null value.
A tool MAY specify the initial start time submissions for this line item can be made by learners. The initial value may subsequently be changed within the platform.
ISO 8601 Date and time when the line item can start receiving submission.
A tool MAY specify the initial end time submissions for this line item can be made by learners. The initial value may subsequently be changed within the platform.
ISO 8601 Date and time when the line item stops receiving submissions.
The tool specifies this optional property when it wishes the grades to be released. It is up to the LMS to decide how to handle this and every LMSes behavior may be different.
A URL pointing to the next page of line items.
A URL pointing to the first page of line items.
A URL pointing to the last page of line items.
A URL pointing to the previous page of line items.
{
"lineItems": [
{
"id": "https://lms.example.com/course/1/lineitems/1",
"label": "Activity",
"scoreMaximum": 100,
"resourceLinkId": "1g3k4dlk49fk",
"resourceId": "a-9334df-33",
"tag": "grade",
"startDateTime": "2024-10-18T18:38:01.063Z",
"endDateTime": "2018-04-06T22:05:03Z",
"gradesReleased": true
}
],
"next": "https://lms.example.com/course/1/lineitems?pages=2",
"first": "https://lms.example.com/course/1/lineitems?pages=1",
"last": "https://lms.example.com/course/1/lineitems?pages=3",
"prev": "string"
}
Unauthorized. Please check our guide on Authenticating API requests to learn about how authentication works in the LTIAAS API.
Schema
Default value: 401
Default value: Unauthorized
details object required
{
"status": 401,
"error": "Unauthorized",
"details": {
"message": "INVALID_LTIK_AUTH_AUTHORIZATION_HEADER",
"description": "Invalid or expired ltik."
}
}
