# List vocabulary suggestions

Words proposed for the organization's vocabulary: members' names, the names of assistants and projects, and words several colleagues learned from their own corrections. Words learned by the most colleagues come first. Needs the right to manage the team vocabulary.

#### Query Parameters

**`state`** string optional

Only this state: `pending`, `approved`, `dismissed` or `shared`.

**`source`** string optional

Only this source: `people`, `assistant`, `project` or `learned`.

**`limit`** integer optional · Defaults to `50`

Page size, 1 to 200.

**`offset`** integer optional · Defaults to `0`

Suggestions to skip, up to 10000.

## Returns

**`object`** string

Always `list`.

**`data`** array

The suggestions:

**`id`** string

The suggestion ID (`vsug_…`).

**`term`** string

The proposed word, as it is written.

**`language`** string or null

The language tag; null for all languages.

**`source`** string

`people` (a member's name), `assistant` (an assistant shared with the organization), `project` (a project name) or `learned` (colleagues who corrected their own transcripts).

**`people_count`** integer or null

How many colleagues learned the word; set for `learned` only.

**`sounds_like`** array of strings

How the word was heard before it was corrected.

**`state`** string

`pending`, `approved`, `dismissed`, or `shared` when written automatically.

**`decided_by_user_id`** string or null

Who decided, if anyone.

**`decided_at`** string or null

When it was decided.

**`list_id`** string or null

The list the word was written into.

**`entry_id`** string or null

The entry that was written.

**`refreshed_at`** string

When the suggestion was last refreshed.

**`total`** integer

How many suggestions match the filters.

**`last_refreshed_at`** string or null

When suggestions were last refreshed; null if never.

Example

```bash cURL
curl -X GET "https://api.aitronos.com/v1/vocabulary/suggestions?state=pending" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/vocabulary/suggestions?state=pending",
    headers={"X-API-Key": api_key},
)

print(response.json())
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/vocabulary/suggestions?state=pending', {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey
  }
});

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

**Response:**


```json 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "vsug_4e8b2d6f1a3c5097",
      "term": "Kubernetes",
      "language": null,
      "source": "learned",
      "people_count": 4,
      "sounds_like": [
        "cube ernetes"
      ],
      "state": "pending",
      "decided_by_user_id": null,
      "decided_at": null,
      "list_id": null,
      "entry_id": null,
      "refreshed_at": "2026-10-26T09:30:00Z"
    }
  ],
  "total": 1,
  "last_refreshed_at": "2026-10-26T09:30:00Z"
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "system_message": "Caller lacks the rights this operation needs.",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-26T09:30:00Z"
  }
}
```

## Related Resources

- [Refresh vocabulary suggestions](/api-reference/vocabulary/refresh-vocabulary-suggestions) — Collect new suggestions now.
- [Update vocabulary settings](/api-reference/vocabulary/update-vocabulary-settings) — Switch suggestions on or off and choose the target list.
- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.