Skip to main content

Retrieve a list of assessments

Developer reference

Abstract

Learn how to retrieve paginated assessment lists so you can surface, manage, and monitor assessment activity through the API.

Use the GET /assessments and GET /assessment-views endpoints to retrieve paginated lists of assessments for an institution or entity. These endpoints are commonly used to support user-facing and operational scenarios such as displaying assessments in a UI, tracking assessment progress and status, or enabling users to select an assessment to view, update, or act on.

Depending on your use case, you can retrieve either core assessment records for processing and integration, or enriched, display-ready assessment data for presenting human-readable information in dashboards and applications.

Request

Two endpoints are available, depending on whether you need lightweight assessment data for backend workflows or display‑oriented details for end-user experiences:

  • GET /assessments: Returns a paginated list of core assessment records.

  • GET /assessment-views: Returns a paginated list of assessment view records enriched with display‑oriented data.

Both endpoints return paginated results and use the same pagination.

To authenticate your request, include the apikey: API_KEY header. See Manage API keys for more information.

Parameters

Both endpoints have one required query parameter. Use max_page_size to set the maximum number of results returned per page.

Optionally, you can filter the assessments returned to those for a single entity using the entity_id query parameter.

Sample request

This example retrieves a paginated list of assessments.

curl --request "GET" \ 
 "https://{api_region}/v5/assessments?max_page_size=50" \ 
 --header "apikey: API_KEY"

Replace {api_region} with the domain from your region's base URL.

If you need human‑readable assessment names or status details for display, replace /assessments with /assessment-views.

Response

A successful request returns a list of assessment objects and, if more results are available, a token for the next page.

Pass the value in next_page_token as page_token in the next request to retrieve the next page of results.

This example shows a response from the GET /assessments endpoint that has returned one assessment object.

{
 "next_page_token": null,  
 "results": [  
  {   
   "created_at": "2026-03-24T14:15:22Z",      
   "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
   "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
   "institution_id": "c75f2c73-5ae4-4f1c-99c0-fc726cd41798",
   "outcome_id": "0323e489-6bf9-4b68-9c8d-5674f46921e4",
   "status_id": "4e949624-bc0f-439e-a9f2-25a23938812c",
   "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",   
   "workflow_instance_id": "46ff49d0-5f69-46b0-9de7-5703639a02ce",   
   "workflow_state": "Active"  
  } 
 ]
}

Troubleshooting

  • If you receive a 401 Unauthorized response, make sure the apikey header is included and contains a valid key. Check that you are using the correct base URL for your region, and if IP allow listing is enabled, verify your request originates from an allowed IP address.

  • If you receive a 400 Bad Request response, check that max_page_size is provided and that all query parameters are valid.

For a full list of possible error responses, see the API reference.

Additional information