> For the complete documentation index, see [llms.txt](https://speaking-test-docs.speechace.com/speechace-speaking-test/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-assessment-results.md).

# Get Assessment Results

Learn how to retrieve candidate attempts, assessment scores, and report information for a specific assessment.

The **Get Assessment Results** endpoint retrieves candidate attempts and results for a specific assessment, including candidate details, scores, completion status, and available report links.

This allows you to access assessment results programmatically for reporting or integration with your own applications.

The below block additionally displays the required path parameters, along with optional query parameters for filtering assessment results. You can explore code examples in different programming languages and review the possible API responses with sample JSON data.

## Get Assessment Results

> Retrieve candidate attempts and scores for an assessment. Optionally filter results by candidate, activity, date range, or attempt status.

```json
{"openapi":"3.0.3","info":{"title":"Speechace Speaking Test API","version":"0.2.5-draft"},"tags":[{"name":"Get Assessment Results"}],"servers":[{"url":"https://speak.speechace.co","description":"Speechace Speaking Test API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"Unauthorized":{"description":"The request could not be authenticated because the API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"ResourceNotFound":{"description":"The requested resource could not be found or accessed. Check the resource identifiers and API key permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}},"schemas":{"APIError":{"type":"object","description":"Error details returned for an unsuccessful request.","required":["error"],"properties":{"error":{"type":"object","required":["message","request_id"],"properties":{"message":{"type":"string","description":"Human-readable error message."},"request_id":{"type":"string","description":"Request identifier used when contacting support."}}}}}}},"paths":{"/api/v1/workspaces/{workspace_id}/assessments/{assessment_id}/results":{"get":{"tags":["Get Assessment Results"],"operationId":"getAssessmentResults","summary":"Get Assessment Results","description":"Retrieve candidate attempts and scores for an assessment. Optionally filter results by candidate, activity, date range, or attempt status.","parameters":[{"name":"workspace_id","required":true,"description":"Workspace ID.","schema":{"type":"string"},"in":"path"},{"name":"assessment_id","required":true,"description":"Assessment ID.","schema":{"type":"string"},"in":"path"},{"name":"speechace_user_id","required":false,"description":"Optional Speechace user ID filter.","schema":{"type":"string"},"in":"query"},{"name":"username","required":false,"description":"Optional username filter.","schema":{"type":"string"},"in":"query"},{"name":"email","required":false,"description":"Optional email filter.","schema":{"type":"string"},"in":"query"},{"name":"date_from","required":false,"description":"Optional ISO 8601 start timestamp, including timezone.","schema":{"type":"string","format":"date-time"},"in":"query"},{"name":"date_to","required":false,"description":"Optional ISO 8601 end timestamp, including timezone.","schema":{"type":"string","format":"date-time"},"in":"query"},{"name":"attempts","required":false,"description":"Optional attempt selection filter. The value `all` is accepted. Other accepted values depend on the API.","schema":{"type":"string"},"in":"query"},{"name":"attempt_state","required":false,"description":"Optional attempt-state filter. The value `completed` is accepted; `all` has also been tested with Assessment Results.","schema":{"type":"string"},"in":"query"},{"name":"activity_id","required":false,"description":"Optional activity ID filter.","schema":{"type":"string"},"in":"query"}],"responses":{"200":{"description":"Successful response containing assessment information, the result period, and candidate attempt records.","content":{"application/json":{"schema":{"type":"object","required":["assessment","result_period","candidate_records"],"properties":{"assessment":{"type":"object","description":"Assessment information and scoring rubric.","properties":{"id":{"type":"string","description":"Assessment identifier."},"title":{"type":"string","description":"Assessment title."},"default_rubric":{"type":"string","description":"Default scoring rubric."}}},"result_period":{"type":"object","description":"Date range covered by the response.","properties":{"date_from":{"type":"string","format":"date-time"},"date_to":{"type":"string","format":"date-time"}}},"candidate_records":{"type":"array","description":"Candidate attempts and their results; a candidate may appear more than once.","items":{"type":"object","properties":{"result_id":{"type":"string","description":"Identifier for this attempt; use it when requesting detailed results."},"attempt_state":{"type":"string","description":"Completion state of this attempt."},"quiz_score":{"type":"number","description":"Score for this dimension, or null when unavailable.","nullable":true},"quiz_cefr":{"type":"string"},"pronunciation_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"fluency_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"vocab_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"grammar_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"task_achievement":{"type":"string","nullable":true},"coherence_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"accountability_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"adaptability_score":{"type":"number","description":"Score for this dimension, or null when unavailable."},"collaboration_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"communication_score":{"type":"number","description":"Score for this dimension, or null when unavailable."},"confidence_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"critical_thinking_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"domain_expertise_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"emotional_intelligence_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"empathy_score":{"type":"number","description":"Score for this dimension, or null when unavailable."},"initiative_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"integrity_score":{"type":"number","description":"Score for this dimension, or null when unavailable."},"leadership_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"learning_agility_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"motivation_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"problem_solving_score":{"type":"number","description":"Score for this dimension, or null when unavailable."},"teamwork_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"time_management_score":{"type":"number","nullable":true,"description":"Score for this dimension, or null when unavailable."},"report_url":{"type":"string","description":"Report link returned for the attempt when available."},"date_of_attempt":{"type":"string","description":"Timestamp of the attempt."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags associated with the attempt."},"proctor":{"type":"string","nullable":true},"username":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"speechace_user_id":{"type":"integer","description":"Speechace user identifier for the candidate."},"invited_on":{"type":"string","nullable":true},"invited_by":{"type":"string","nullable":true},"activity_id":{"type":"string","description":"Activity identifier used to retrieve activity-level results."},"quiz_name":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/ResourceNotFound"}}}}}}
```

#### Filtering assessment results

As indicated above , you can use optional query parameters to narrow assessment results by candidate, activity, date range, or attempt status.

You can filter by `username`, `email`, `speechace_user_id`, `activity_id`, `date_from`, `date_to`, `attempts`, and `attempt_state`.

For supported filter values, empty responses, and common API errors, see [**Filters, Errors and Examples**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/filters-errors-and-examples.md).

The following section describes [**Get Activity Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-activity-results.md) and how to retrieve results for a specific activity within an assessment.
