Feedback: speech-to-text-pre-recorded-audio-delete-transcripts

Documentation Feedback

Original URL: https://assemblyai.com/docs/speech-to-text/pre-recorded-audio/delete-transcripts
Category: speech-to-text
Generated: 05/08/2025, 4:26:01 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:26:00 pm

Technical Documentation Feedback: Delete Transcripts

Overall Assessment

This documentation covers the basic functionality but has several critical gaps that could frustrate users. The structure is code-heavy without sufficient explanation, and key information is missing or unclear.

Critical Issues to Address

1. Missing Essential Information

Problem: No clear explanation of what happens when a transcript is deleted

• Add: Explicit description that deletion removes transcript data permanently
• Add: Information about what data is retained vs. deleted (metadata, billing records, etc.)
• Add: Clarification on deletion confirmation - is it immediate or eventual consistency?

Problem: No API response documentation

• Add: Expected response format for successful deletion
• Add: Common error responses and their meanings
• Add: HTTP status codes users should expect

2. Confusing Code Examples

Problem: Python SDK example shows contradictory behavior

transcript.delete_by_id(transcript.id)
transcript = aai.Transcript.get_by_id(transcript.id)  # What happens here?
print(transcript.text)  # Will this work after deletion?

Fix:

• Explain what get_by_id() returns after deletion
• Show error handling for accessing deleted transcripts
• Demonstrate proper verification of deletion

Problem: Raw API examples are unnecessarily complex

• Simplify: Focus on the deletion operation, not the full transcription workflow
• Add: Standalone deletion example with just transcript ID

3. Poor Information Hierarchy

Current structure problems:

• No overview or prerequisites section
• Code examples dominate without context
• Important TTL information buried at the bottom

Recommended structure:

# Delete Transcripts

## Overview
Brief explanation of deletion functionality and use cases

## Prerequisites
- Valid API key
- Existing transcript ID

## Deletion Methods
### Using SDKs
### Using REST API

## Response Format
### Success Response
### Error Responses

## Important Considerations
- TTL information
- Data retention policies
- Billing implications

4. Inadequate Examples

Add missing examples:

# Simple deletion example
transcript_id = "your-transcript-id"
response = client.transcripts.delete(transcript_id)
print(f"Deletion status: {response.status}")

Add error handling examples:

try:
    client.transcripts.delete(transcript_id)
    print("Transcript deleted successfully")
except TranscriptNotFoundError:
    print("Transcript not found or already deleted")
except APIError as e:
    print(f"Deletion failed: {e}")

5. Unclear TTL Section

Problems with current TTL explanation:

• Confusing timeline references (“Starting on 11-26-2024”)
• Unclear which customers are affected
• Vague language (“subject to change”)

Improvements needed:

• Lead with clear statement: “Some accounts have automatic transcript deletion”
• Explain how users can check if TTL applies to their account
• Provide specific steps to determine TTL settings
• Clarify interaction between manual deletion and TTL

Specific Actionable Improvements

1. Add Introduction Section

## Overview
The delete transcript endpoint permanently removes transcript data from AssemblyAI's servers. Once deleted, the transcript text and associated metadata cannot be recovered.

**Use cases:**
- Data privacy compliance
- Storage management
- Removing sensitive content

**What you'll need:**
- Valid API key
- Transcript ID of the transcript to delete

2. Document API Response

## Response Format

### Successful Deletion
```json
{
  "id": "transcript_id",
  "status": "deleted",
  "text": null,
  "created": "2024-01-01T00:00:00Z",
  "completed": "2024-01-01T00:05:00Z"
}

Error Responses

• 404 Not Found: Transcript doesn’t exist or was already deleted
• 401 Unauthorized: Invalid API key
• 403 Forbidden: No permission to delete this transcript

### 3. Improve Code Examples
- Remove full transcription workflow from deletion examples
- Add standalone deletion examples
- Include proper error handling
- Show verification of deletion success

### 4. Add Troubleshooting Section
```markdown
## Troubleshooting

**Q: Can I recover a deleted transcript?**
A: No, deletion is permanent and irreversible.

**Q: What happens if I try to delete a transcript twice?**
A: The API returns a 404 error for already-deleted transcripts.

**Q: How do I know if deletion was successful?**
A: Check the response status or attempt to retrieve the transcript (should return 404).

5. Clarify TTL Information

• Move TTL information to a clearly labeled section
• Explain how to check if your account has TTL enabled
• Provide contact information for TTL-related questions
• Use clear, present-tense language instead of future dates

User Experience Pain Points

1. Cognitive overload: Too much code, not enough explanation
2. Unclear outcomes: Users don’t know what to expect after deletion
3. Missing context: No explanation of why someone would delete transcripts
4. Poor discoverability: Important information hidden in code comments and footnotes

Priority Recommendations

1. High Priority: Add API response documentation and clarify deletion behavior
2. High Priority: Simplify code examples and add error handling
3. Medium Priority: Restructure information hierarchy
4. Medium Priority: Clarify TTL section with actionable information
5. Low Priority: Add troubleshooting and FAQ sections

These improvements will significantly enhance user understanding and reduce support requests while making the documentation more actionable and user-friendly.

---