Summary This source did not publish a separate summary. Review SKILL.md before using the skill.
AssemblyAI Production Checklist
Overview
Complete checklist for deploying AssemblyAI-powered transcription services to production with health checks, monitoring, and rollback procedures.
Prerequisites
Instructions
Pre-Deployment Checklist
API Key & Auth
Code Quality
Error Handling
transcript.status === 'error' logged with transcript ID and error message
Performance
Health Check Implementation import { AssemblyAI } from 'assemblyai';
const client = new AssemblyAI({
apiKey: process.env.ASSEMBLYAI_API_KEY!,
});
export async function healthCheck(): Promise<{
status: 'healthy' | 'degraded' | 'down';
assemblyai: { connected: boolean; latencyMs: number };
}> {
const start = Date.now();
try {
// List transcripts as a lightweight connectivity check
await client.transcripts.list({ limit: 1 });
return {
status: 'healthy',
assemblyai: { connected: true, latencyMs: Date.now() - start },
};
} catch (error) {
return {
status: 'degraded',
assemblyai: { connected: false, latencyMs: Date.now() - start },
};
}
}
Webhook-Based Processing (Recommended for Production) // Instead of polling, use webhooks for transcription completion
const transcript = await client.transcripts.submit({
audio: audioUrl,
webhook_url: 'https://your-app.com/webhooks/assemblyai',
webhook_auth_header_name: 'X-Webhook-Secret',
webhook_auth_header_value: process.env.ASSEMBLYAI_WEBHOOK_SECRET!,
speaker_labels: true,
sentiment_analysis: true,
});
console.log('Submitted:', transcript.id, '(webhook will fire on completion)');
// Webhook handler
import express from 'express';
app.post('/webhooks/assemblyai', express.json(), async (req, res) => {
// Verify auth header
const secret = req.headers['x-webhook-secret'];
if (secret !== process.env.ASSEMBLYAI_WEBHOOK_SECRET) {
return res.status(401).json({ error: 'Unauthorized' });
}
const { transcript_id, status } = req.body;
if (status === 'completed') {
// Fetch full transcript
const transcript = await client.transcripts.get(transcript_id);
await processCompletedTranscript(transcript);
} else if (status === 'error') {
console.error(`Transcript ${transcript_id} failed:`, req.body.error);
await handleFailedTranscript(transcript_id, req.body.error);
}
res.status(200).json({ received: true });
});
Monitoring & Alerting Alert Condition Severity API unreachable Health check fails 3x consecutive P1 High error rate >5% of transcriptions fail P2 Rate limited 429 errors > 5/min P2 Auth failure Any 401 response P1 Slow transcription Queue wait > 5 min P3 Webhook delivery failure Webhook retries exhausted P2
Gradual Rollout # 1. Pre-flight: verify AssemblyAI API is healthy
curl -s https://status.assemblyai.com/api/v2/status.json | jq '.status.description'
# 2. Deploy to canary (10% traffic)
# 3. Monitor error rate and latency for 10 minutes
# 4. If healthy, roll to 50%, then 100%
# 5. Keep previous version ready for instant rollback
Output
Production-ready deployment with health checks
Webhook-based transcription processing
Monitoring and alerting configuration
Gradual rollout strategy
Error Handling Issue Detection Response API key invalid in prod 401 on first call Rotate key immediately Transcription backlog Queue size growing Scale workers, check rate limits Webhook endpoint down Missed completion events Poll for stuck transcripts Audio upload timeout Large file failures Increase timeout, validate file size
Resources
Next Steps For version upgrades, see assemblyai-upgrade-migration.
