Feedback: api-reference-transcripts-list

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/transcripts/list
Category: api-reference
Generated: 05/08/2025, 4:31:07 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:31:06 pm

Technical Documentation Analysis & Recommendations

Critical Issues Requiring Immediate Attention

1. Broken Examples Section

Problem: The examples section contains 8 nearly identical code blocks that all show the same status=queued filter.

Fix: Replace with diverse, meaningful examples:

# Basic request - get latest transcripts
curl https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY"

# Filter by status
curl -G https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -d status=completed

# Limit results and filter by date
curl -G https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -d limit=10 \
     -d created_on=2024-01-15

# Pagination example
curl -G https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -d before_id=abc123def \
     -d limit=20

2. Missing Response Schema

Problem: No example of what a successful response looks like.

Add:

{
  "page": {
    "limit": 10,
    "current_url": "https://api.assemblyai.com/v2/transcript?limit=10",
    "prev_url": "https://api.assemblyai.com/v2/transcript?limit=10&before_id=xyz789",
    "next_url": "https://api.assemblyai.com/v2/transcript?limit=10&after_id=abc123"
  },
  "transcripts": [
    {
      "id": "abc123def456",
      "language_model": "assemblyai_default",
      "acoustic_model": "assemblyai_default",
      "language_code": "en_us",
      "status": "completed",
      "audio_url": "https://example.com/audio.mp3",
      "text": "This is the transcribed text...",
      "words": null,
      "confidence": 0.95,
      "audio_duration": 120.5,
      "created": "2024-01-15T10:30:00.000Z",
      "completed": "2024-01-15T10:32:15.000Z"
    }
  ]
}

Structure & Organization Improvements

3. Reorganize Content Flow

Current order: Endpoint → Note → Description → Parameters → Response → Examples Better order:

1. Endpoint & Description
2. Authentication note
3. Parameters (with better formatting)
4. Request Examples
5. Response Schema & Examples
6. Error Handling
7. Usage Notes

4. Improve Parameter Documentation

Current: Vague bullet points Better: Structured table format

Parameter	Type	Required	Description	Example
limit	integer	No	Maximum transcripts to return (1-100, default: 10)	?limit=25
status	string	No	Filter by status: queued, processing, completed, error	?status=completed
created_on	string	No	Filter by creation date (YYYY-MM-DD format)	?created_on=2024-01-15
before_id	string	No	Get transcripts created before this ID (pagination)	?before_id=abc123
after_id	string	No	Get transcripts created after this ID (pagination)	?after_id=xyz789
throttled_only	boolean	No	Show only throttled transcripts (overrides status filter)	?throttled_only=true

Missing Critical Information

5. Authentication Details

Add section:

## Authentication
All requests require your API key in the Authorization header:

Authorization: YOUR_API_KEY

Get your API key from the [AssemblyAI Dashboard](https://assemblyai.com/dashboard).

6. Pagination Explanation

Add section:

## Pagination
This endpoint uses cursor-based pagination:
- Use `before_id` to get older transcripts
- Use `after_id` to get newer transcripts
- The `page` object in the response contains URLs for navigation
- Maximum `limit` is 100 transcripts per request

7. Rate Limiting Information

Expand on the 429 error:

## Rate Limits
- Standard: 100 requests per minute
- When exceeded, you'll receive a 429 status code
- Check the `Retry-After` header for wait time

User Experience Enhancements

8. Add SDK Examples

Include examples in popular languages:

# Python
import assemblyai as aai
aai.settings.api_key = "YOUR_API_KEY"

transcripts = aai.Transcript.list(
    status=aai.TranscriptStatus.completed,
    limit=10
)

// JavaScript
import { AssemblyAI } from 'assemblyai'

const client = new AssemblyAI({
  apiKey: 'YOUR_API_KEY'
})

const transcripts = await client.transcripts.list({
  status: 'completed',
  limit: 10
})

9. Add Common Use Cases Section

## Common Use Cases

### Get your 10 most recent completed transcripts
```shell
curl -G https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -d status=completed \
     -d limit=10

Check for failed transcriptions from today

curl -G https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -d status=error \
     -d created_on=$(date +%Y-%m-%d)

### 10. **Error Handling Guidance**
**Expand error section**:
```markdown
## Error Responses

| Status Code | Description | Common Causes |
|-------------|-------------|---------------|
| 400 | Bad Request | Invalid parameter values, malformed date |
| 401 | Unauthorized | Missing or invalid API key |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Temporary server issue, retry after delay |

### Example Error Response
```json
{
  "error": "Invalid status parameter",
  "message": "Status must be one of: queued, processing, completed, error"
}

## Quick Wins

### 11. **Fix Authorization Header Format**
Change `Authorization: <apiKey>` to `Authorization: YOUR_API_KEY` for consistency.

### 12. **Add Response Time Expectations**
"This endpoint typically responds within 200-500ms."

### 13. **Cross-reference Related Endpoints**
Add "See Also" section linking to:
- Create transcript endpoint
- Get transcript by ID endpoint
- Delete transcript endpoint

These improvements will significantly enhance the documentation's usability and reduce user confusion.

---