> 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-candidate-results.md).

# Get Candidate Results

Retrieve assessment-level and activity-level results for a specific candidate using the Speechace Speaking Test API.

The **Get Candidate Results** endpoint retrieves results for a specific candidate within an assessment.

Depending on the level of detail you need, you can retrieve an assessment-level result or individual activity-level results. This allows you to review a candidate's overall assessment performance or explore their results for specific activities.

The endpoint uses the candidate's identifier together with the workspace and assessment IDs to locate the relevant results.

### Understanding candidate result levels

The API supports two levels of candidate results:

* **Assessment level:** Retrieves results for the candidate within the selected assessment, including assessment-level information and associated activity records.
* **Activity level:** Retrieves individual activity results for the candidate within the selected assessment.

You can choose which level to retrieve using the `result_level` query parameter. The following section shows how to request each level and understand its response.

## Get Candidate Results

> Retrieve results for a specific candidate within an assessment. Use result\_level=assessment to include individual activity records and an overall assessment summary, or result\_level=activity to retrieve the individual activity records without the assessment summary.

```json
{"openapi":"3.0.3","info":{"title":"Speechace Speaking Test API","version":"0.2.5-draft"},"tags":[{"name":"Get Candidate 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}/candidates/{candidate_id}/results":{"get":{"tags":["Get Candidate Results"],"operationId":"getCandidateResults","summary":"Get Candidate Results","description":"Retrieve results for a specific candidate within an assessment. Use result_level=assessment to include individual activity records and an overall assessment summary, or result_level=activity to retrieve the individual activity records without the assessment summary.","parameters":[{"name":"workspace_id","required":true,"description":"Workspace identifier returned by List Workspaces.","schema":{"type":"string"},"in":"path"},{"name":"assessment_id","required":true,"description":"Assessment identifier returned by List Assessments. A candidate may have results in multiple assessments.","schema":{"type":"string"},"in":"path"},{"name":"candidate_id","required":true,"description":"Candidate identifier, taken from speechace_user_id in Get Assessment Results.","schema":{"type":"string"},"in":"path"},{"name":"result_level","required":false,"description":"Choose assessment to include activity results and the overall assessment summary, or activity for individual activity results without the summary.","schema":{"type":"string","enum":["assessment","activity"],"default":"assessment"},"in":"query"},{"name":"date_from","required":false,"description":"Optional ISO 8601 timestamp including a timezone.","schema":{"type":"string","format":"date-time"},"in":"query"},{"name":"date_to","required":false,"description":"Optional ISO 8601 timestamp including a timezone.","schema":{"type":"string","format":"date-time"},"in":"query"},{"name":"include_incomplete","required":false,"description":"Optional flag to include incomplete results (true).","schema":{"type":"boolean"},"in":"query"}],"responses":{"200":{"description":"Successful response containing the candidate’s activity results; assessment-level results also include an overall assessment summary.","content":{"application/json":{"schema":{"type":"object","required":["assessment","candidate","result_level","activity_records"],"properties":{"assessment":{"type":"object","description":"Assessment associated with these candidate results.","properties":{"id":{"type":"string","description":"Assessment identifier."},"title":{"type":"string","description":"Assessment title."},"default_rubric":{"type":"string","description":"Scoring rubric associated with the assessment."}}},"candidate":{"type":"object","description":"Identifying information for the requested candidate.","properties":{"id":{"type":"string","description":"Candidate identifier used in the URL."},"speechace_user_id":{"type":"integer","description":"Speechace user identifier; may be used as candidate_id in requests."},"username":{"type":"string","description":"Candidate username."},"full_name":{"type":"string","description":"Candidate full name."},"email":{"type":"string","description":"Candidate email address.","format":"email"}}},"result_level":{"type":"string","enum":["assessment","activity"],"description":"Level of result detail requested."},"activity_records":{"type":"array","description":"One record per returned activity result; repeated attempts may produce multiple records.","items":{"type":"object","description":"Individual activity attempt and score. Each record has its own result_id.","properties":{"result_id":{"type":"string","description":"Unique identifier for this activity result."},"attempt_state":{"type":"string","description":"Completion status of this activity attempt."},"quiz_score":{"type":"number","description":"Score reported for this activity attempt."},"quiz_cefr":{"type":"string","description":"CEFR level reported for this activity attempt."},"activity_id":{"type":"string","description":"Identifier of the activity."},"activity_title":{"type":"string","description":"Display title of the activity."}}}},"assessment_summary":{"type":"object","description":"Overall assessment score, included in the documented assessment-level example and absent from the activity-level example.","properties":{"overall_score":{"type":"number","description":"Overall assessment score."},"rubric":{"type":"string","description":"Rubric used for the summary."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/ResourceNotFound"}}}}}}
```

### Why is an assessment ID needed?

A candidate can complete more than one assessment within the same workspace.

The `assessment_id` tells the API which assessment you want results for, while the `candidate_id` identifies the candidate.

For example, a candidate who has completed both an HR Interview and a Sales Manager Interview will have results associated with each assessment.

To retrieve their results, you can make a separate request for each assessment using its corresponding `assessment_id` and the same `candidate_id`.

### Finding the candidate ID

Before retrieving results for a specific candidate, you'll need their `candidate_id`.

You can use [**Get Assessment Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-assessment-results.md) to retrieve candidate records for an assessment. Each record includes a `speechace_user_id`, along with identifying information such as the candidate's name, username, and email address.

Use the `speechace_user_id` value as the `candidate_id` in your **Get Candidate Results** request.

For example, a candidate record might contain:

```json
{
  "speechace_user_id": 3097239,
  "username": "candidate1",
  "full_name": "Example Candidate",
  "email": "candidate1@example.com"
}
```

In the above example, use `3097239` as the `candidate_id` in your **Get Candidate Results** request.

A candidate may have multiple attempts, each with its own `result_id`, while the `speechace_user_id` identifies the candidate across those attempts.

Use the candidate's name, username, or email to locate the correct record before making your request.

The following section describes [**Get Detailed Activity Result** ](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-detailed-activity-result.md)and how to retrieve more detailed information using a specific result identifier.
