> 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/list-workspaces-assessments-and-activities.md).

# List Workspaces, Assessments, and Activities

Learn how to retrieve Workspaces , Assessments and Activities using Speechace Speaking Test API .

Before you start working with the **Speechace Speaking Test API**, you'll need to know which workspaces, assessments, and activities are available to you. The API lets you retrieve these details.&#x20;

### Understanding the resource hierarchy

Before retrieving results, it helps to understand how workspaces, assessments, and activities are organized in **Speechace** platform.

As shown below , a workspace contains assessments, and each assessment can contain zero or more activities.

```
Workspace (7898)
└── Assessment (13971)
    └── Activity (20471)
```

Each level has its own identifier, which you'll use when making subsequent API requests.

***

### List Workspaces

Let's start by finding the workspaces available to your API key.

The **List Workspaces** endpoint returns the workspaces you can access, along with their identifiers and other details. You'll use these identifiers to retrieve assessments within a specific workspace.

The block below displays the request details, including the HTTP method, endpoint URL, and authentication requirements. You can also select your preferred programming language to view the code example and explore the expected response structure.

## List Workspaces

> Retrieve workspaces accessible to your API key.

```json
{"openapi":"3.0.3","info":{"title":"Speechace Speaking Test API","version":"0.2.5-draft"},"tags":[{"name":"Workspaces","description":"Workspace discovery"}],"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"}}}}},"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":{"get":{"tags":["Workspaces"],"operationId":"listWorkspaces","summary":"List Workspaces","description":"Retrieve workspaces accessible to your API key.","responses":{"200":{"description":"Successful response in JSON containing accessible workspaces.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Workspaces accessible to your API key.","items":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","description":"Unique workspace identifier used in subsequent API requests."},"name":{"type":"string","description":"Display name of the workspace."},"status":{"type":"string","description":"Current workspace status."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

***

### List Assessments

Now that you've identified your workspace, the next step is to find the assessments within it.

The **List Assessments** endpoint returns the assessments belonging to a specific workspace, along with their identifiers and other available details. You'll use these identifiers when retrieving assessment results or exploring the activities within an assessment.

As you can see below are the request details, the HTTP method, endpoint URL, and authentication requirements. You can switch between programming languages to find a suitable code example, and examine the sample responses to see what the API returns.

## List Assessments

> Retrieve assessments belonging to a specified workspace. Use the assessment ID, not the assessment name, in subsequent API requests because names may repeat. The activity\_count field indicates the number of activities within an assessment.

```json
{"openapi":"3.0.3","info":{"title":"Speechace Speaking Test API","version":"0.2.5-draft"},"tags":[{"name":"List Assessments"}],"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":{"get":{"tags":["List Assessments"],"operationId":"listAssessments","summary":"List Assessments","description":"Retrieve assessments belonging to a specified workspace. Use the assessment ID, not the assessment name, in subsequent API requests because names may repeat. The activity_count field indicates the number of activities within an assessment.","parameters":[{"name":"workspace_id","required":true,"description":"Workspace identifier returned by List Workspaces.","schema":{"type":"string"},"in":"path"}],"responses":{"200":{"description":"Successful response containing assessments within the specified workspace.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Assessments within the specified workspace.","items":{"type":"object","properties":{"id":{"type":"string","description":"Assessment identifier used in subsequent API requests."},"name":{"type":"string","description":"Assessment display name. Names may be repeated; use the assessment ID to identify an assessment."},"status":{"type":"string","description":"Current assessment status."},"language":{"type":"string","nullable":true,"description":"Assessment language, or null when no language is specified."},"activity_count":{"type":"integer","minimum":0,"description":"Number of activities belonging to this assessment; may be zero."}},"required":["id","name","status","language","activity_count"]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/ResourceNotFound"}}}}}}
```

***

### List Activities

Once you've identified the assessment you want to work with, you can retrieve the activities associated with it.

The **List Activities** endpoint returns the activities belonging to a specific assessment, along with their identifiers and other available details. You can use these activity IDs when retrieving activity-level results.

The below block shows the request details, the HTTP method, endpoint URL, and authentication requirements. It also includes code examples in multiple programming languages and sample responses to help you understand the returned data.

## List Activities

> Retrieve activities belonging to a specific assessment. Use each activity ID when requesting activity-level results.

```json
{"openapi":"3.0.3","info":{"title":"Speechace Speaking Test API","version":"0.2.5-draft"},"tags":[{"name":"List Activities"}],"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}/activities":{"get":{"tags":["List Activities"],"operationId":"listActivities","summary":"List Activities","description":"Retrieve activities belonging to a specific assessment. Use each activity ID when requesting activity-level results.","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.","schema":{"type":"string"},"in":"path"}],"responses":{"200":{"description":"Successful response containing activities within the specified assessment.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Activities associated with the specified assessment.","items":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","description":"Activity identifier used in subsequent API requests."},"name":{"type":"string","description":"Display name of the activity."},"status":{"type":"string","description":"Current activity status."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/ResourceNotFound"}}}}}}
```

You now have the workspace, assessment, and activity IDs needed to retrieve results.

The following section describes [**Get Assessment Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-assessment-results.md) and how to retrieve assessment-level results, Once you have the required workspace, assessment, and activity IDs.
