> 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/filters-errors-and-examples.md).

# Filters, Errors and Examples

Learn how to use filters to narrow down assessment results by candidate, activity, or date.

This page covers the available filtering options, examples of common requests, and how the API responds when no records match or a request cannot be processed.

### Filtering Results

The **Speaking Test API** supports query parameters that help you retrieve the records relevant to your application.

Filters can be added to the URL of the appropriate results endpoint.

#### Supported query parameters

The table below summarizes the available filtering parameters and indicates which results endpoints support each one.

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Assessment Results</strong></td><td><strong>Activity Results</strong></td><td><strong>Candidate Results</strong></td></tr><tr><td><code>username</code></td><td>Supported</td><td>Supported</td><td>—</td></tr><tr><td><code>email</code></td><td>Supported</td><td>Supported</td><td>—</td></tr><tr><td><code>speechace_user_id</code></td><td>Supported</td><td>Supported</td><td>—</td></tr><tr><td><code>date_from</code></td><td>Supported</td><td>Supported</td><td>Supported</td></tr><tr><td><code>date_to</code></td><td>Supported</td><td>Supported</td><td>Supported</td></tr><tr><td><code>attempts</code></td><td>Supported</td><td>Supported</td><td>—</td></tr><tr><td><code>attempt_state</code></td><td>Supported</td><td>Supported</td><td>—</td></tr><tr><td><code>result_level</code></td><td>—</td><td>—</td><td>Supported</td></tr><tr><td><code>include_incomplete</code></td><td>—</td><td>—</td><td>Supported</td></tr></tbody></table>

#### Filtering by attempt status

The [**Get** **Assessment Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-assessment-results.md) and [**Get Activity Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-activity-results.md) endpoints support optional parameters for controlling which attempts are returned.

* `attempts`: Controls which attempts are included in the response. Use `all` to request all attempts.
* `attempt_state`: Filters results by attempt status. Use `completed` to retrieve completed attempts, or `all` to include attempts across statuses.

To include incomplete results when retrieving results for a specific candidate, use the `include_incomplete` parameter on [**Get Candidate Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-candidate-results.md).

Invalid values for supported filter parameters return `400 Bad Request` with an error message describing the invalid choice.

***

### Example — Filter Results by Date

Retrieve assessment results for attempts recorded during a specific date range.

#### Example request

The below example demonstrates how to retrieve assessment results within a specified date range using the `date_from` and `date_to` query parameters. Select your preferred programming language to view the corresponding request code.

{% tabs %}
{% tab title="cURL" %}
{% code expandable="true" %}

```bash
curl --get \
  'https://speak.speechace.co/api/v1/workspaces/7898/assessments/13971/results' \
  --header 'Authorization: Bearer YOUR_RESULTS_API_KEY' \
  --header 'Accept: application/json' \
  --data-urlencode 'date_from=2026-10-14T00:00:00Z' \
  --data-urlencode 'date_to=2026-10-16T23:59:59Z'

```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code expandable="true" %}

```python
import requests

url = "https://speak.speechace.co/api/v1/workspaces/7898/assessments/13971/results"

headers = {
    "Authorization": "Bearer YOUR_RESULTS_API_KEY",
    "Accept": "application/json"
}

params = {
    "date_from": "2026-10-14T00:00:00Z",
    "date_to": "2026-10-16T23:59:59Z"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
{% code expandable="true" %}

```javascript
const url = new URL(
  "https://speak.speechace.co/api/v1/workspaces/7898/assessments/13971/results"
);

url.searchParams.set("date_from", "2026-10-14T00:00:00Z");
url.searchParams.set("date_to", "2026-10-16T23:59:59Z");

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_RESULTS_API_KEY",
    Accept: "application/json"
  }
});

const data = await response.json();
console.log(data);

```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code expandable="true" %}

```php

<?php

$apiKey = getenv('SPEECHACE_RESULTS_API_KEY');

$url = 'https://speak.speechace.co/api/v1/workspaces/7898/assessments/13971/results';

$queryParams = [
    'date_from' => '2026-10-14T00:00:00Z',
    'date_to' => '2026-10-16T23:59:59Z'
];

$url .= '?' . http_build_query($queryParams);

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json'
    ]
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}

$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($statusCode < 200 || $statusCode >= 300) {
    throw new RuntimeException(
        "API request failed with status $statusCode: $response"
    );
}

echo $response;

```

{% endcode %}
{% endtab %}

{% tab title=".NET (C#)" %}
{% code expandable="true" %}

```c#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

var apiKey = Environment.GetEnvironmentVariable(
    "SPEECHACE_RESULTS_API_KEY"
) ?? throw new InvalidOperationException("Missing API key");

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json")
);

var baseUrl =
    "https://speak.speechace.co/api/v1/workspaces/7898/assessments/13971/results";

var dateFrom = Uri.EscapeDataString("2026-10-14T00:00:00Z");
var dateTo = Uri.EscapeDataString("2026-10-16T23:59:59Z");

var url = $"{baseUrl}?date_from={dateFrom}&date_to={dateTo}";

using var response = await client.GetAsync(url);

response.EnsureSuccessStatusCode();

var responseBody = await response.Content.ReadAsStringAsync();

Console.WriteLine(responseBody);

```

{% endcode %}
{% endtab %}
{% endtabs %}

Dates use ISO 8601 timestamps with timezone information. The `Z` suffix indicates UTC.

These date filters are also available on the [**Get Activity Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-activity-results.md) and [**Get Candidate Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-candidate-results.md) endpoints.

***

### Empty Results

For the [**Assessment Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-assessment-results.md) endpoint, a successful request with no matching attempts returns an empty `candidate_records` array.

#### Example response — 200 OK

The below example shows a successful API response when no candidate attempts match the specified filters. The response returns an empty `candidate_records` array while retaining the assessment and result-period information.

{% code expandable="true" %}

```json
{
  "assessment": {
    "id": "13971",
    "title": "HR Interview",
    "default_rubric": "Speechace"
  },
  "result_period": {
    "date_from": "2026-09-01T00:00:00Z",
    "date_to": "2026-09-02T23:59:59Z"
  },
  "candidate_records": []
}

```

{% endcode %}

***

### Error Responses

When a request cannot be processed, the API returns an HTTP error status and a JSON error message.

The following examples illustrate common API errors, their corresponding HTTP status codes, and the JSON responses developers may encounter when a request fails.

#### Common errors observed

| **HTTP status**    | **Scenario**                 | **Error message**                                  |
| ------------------ | ---------------------------- | -------------------------------------------------- |
| `400 Bad Request`  | Date range is reversed       | `date_from must not be later than date_to.`        |
| `400 Bad Request`  | Invalid timestamp format     | ISO 8601 timestamp required                        |
| `400 Bad Request`  | Unsupported query parameter  | `Unsupported query parameter: include_incomplete.` |
| `401 Unauthorized` | Missing or invalid API key   | `Invalid API key.`                                 |
| `404 Not Found`    | Requested resource not found | `The requested resource was not found.`            |

#### 401 — Invalid API Key

A **401 error** occurs when a request is made without a valid API key.

```json

{
  "error": {
    "message": "Invalid API key.",
    "request_id": "EXAMPLE_REQUEST_ID"
  }
}

```

Check that the API key is valid and included as a Bearer token in the `Authorization` header.

#### 404 — Resource Not Found

A **404 error** occurs when the requested resource cannot be found. Check that the workspace, assessment, activity, or result ID is correct and accessible.

```json
{
  "error": {
    "message": "The requested resource was not found.",
    "request_id": "EXAMPLE_REQUEST_ID"
  }
}

```

#### 400 — Invalid Date Range

A **400 error** occurs when `date_from` is later than `date_to`. Make sure the start date is earlier than or equal to the end date before sending the request.

```json
{
  "error": {
    "message": "date_from must not be later than date_to.",
    "request_id": "EXAMPLE_REQUEST_ID"
  }
}

```

#### 400 — Invalid Date Format

A **400 error** occurs when a date parameter isn't provided in the expected format. Use an ISO 8601 timestamp with a timezone, such as `2026-09-01T00:00:00Z`.

```json
{
  "error": {
    "message": "date_from: Enter an ISO 8601 timestamp with a timezone, e.g. 2026-09-01T00:00:00Z.",
    "request_id": "EXAMPLE_REQUEST_ID"
  }
}

```

#### 400 — Unsupported Query Parameter

A **400 error** occurs when a request includes a query parameter that isn't supported by the endpoint. Check the supported query parameters before sending the request again.

Query parameters are endpoint-specific. A parameter supported by one endpoint may not be accepted by another. For example, `include_incomplete` is documented for [**Get Candidate Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-candidate-results.md) but should not be used with [**Get Assessment Results**](https://speaking-test-docs.speechace.com/speechace-speaking-test/speaking-test-api/get-assessment-results.md) unless supported.

```json
{
  "error": {
    "message": "Unsupported query parameter: include_incomplete.",
    "request_id": "EXAMPLE_REQUEST_ID"
  }
}

```

#### 400 — Invalid Attempt Filter

A `400 Bad Request` response may occur when an unsupported value is supplied for `attempts` or `attempt_state`.

For example below , an invalid `attempt_state` value may return:

```json
{
  "error": {
    "message": "attempt_state: \"invalid_test_value\" is not a valid choice.",
    "request_id": "EXAMPLE_REQUEST_ID"
  }
}
```

Check that the filter value is supported by the endpoint before retrying the request.

***

### Troubleshooting

If an API request doesn't return the expected data, check the endpoint URL, workspace and assessment identifiers, query parameters, and API key.

For empty responses, confirm that the selected candidate, activity, or date range has matching assessment records.

Error responses include a `request_id` that can help identify a specific failed request when contacting **Speechace** support.
