Check Session Status

Poll transcription session status to monitor processing progress and detect completion.

Endpoint

GET /api/v3/speech-to-text/session/{session_id}

Base URL: https://api.scriptix.io

Authentication: Required (Batch token)

Parameters:

• {session_id} - Session identifier returned from upload

Request

Example Request

cURL:

curl https://api.scriptix.io/api/v3/speech-to-text/session/abc123def456 \
  -H "Authorization: Bearer YOUR_BATCH_TOKEN"

JavaScript (fetch):

const response = await fetch(
  'https://api.scriptix.io/api/v3/speech-to-text/session/abc123def456',
  {
    headers: {
      'Authorization': `Bearer ${YOUR_TOKEN}`
    }
  }
);

const session = await response.json();
console.log('Status:', session.status);

Python:

import requests

url = 'https://api.scriptix.io/api/v3/speech-to-text/session/abc123def456'
headers = {'Authorization': f'Bearer {YOUR_TOKEN}'}

response = requests.get(url, headers=headers)
session = response.json()

print('Status:', session['status'])

Response

Session Object

{
  "id": 12345,
  "session_id": "abc123def456",
  "status": "completed",
  "filename": "meeting.mp3",
  "duration": 3600.5,
  "language": "en",
  "media_type": "audio/mpeg",
  "media_url": "https://storage.scriptix.io/media/abc123def456/meeting.mp3",
  "error": null,
  "created_at": "2025-01-15T10:00:00Z",
  "started_at": "2025-01-15T10:01:30Z",
  "finished_at": "2025-01-15T10:15:45Z",
  "document": {
    "id": 67890,
    "name": "meeting.mp3 Transcript",
    "type": "transcript"
  },
  "session_mode": "decode",
  "custom_model_id": null
}

Response Fields

Field	Type	Description
id	Integer	Internal session ID
session_id	String	Unique session identifier
status	String	Processing status (see below)
filename	String	Original uploaded filename
duration	Number	Audio duration in seconds (0 until processed)
language	String	Language code
media_type	String	MIME type of uploaded file
media_url	String	URL to uploaded media file
error	String	Error message if status is failed
created_at	String	ISO 8601 upload timestamp
started_at	String	ISO 8601 processing start timestamp
finished_at	String	ISO 8601 completion timestamp
document	Object	Document info (present when status is completed)
session_mode	String	Mode: decode, align, or upload
custom_model_id	Integer	Custom model ID (if used)

Session Statuses

Sessions progress through these statuses:

Status	Description	Next Action
queued	Uploaded, waiting to process	Continue polling
processing	Actively transcribing	Continue polling
completed	Finished successfully	Retrieve document
failed	Error occurred	Check error field

Status Flow

queued → processing → completed
                   ↘
                    failed

Typical Durations

Audio Length	Queued	Processing	Total
5 minutes	0-1 min	0.5-2 min	1-3 min
30 minutes	0-2 min	3-10 min	3-12 min
1 hour	0-2 min	6-20 min	6-22 min
3 hours	0-3 min	18-60 min	20-65 min

Note: Times vary based on system load and audio complexity.

Polling

Basic Polling Loop

async function pollUntilComplete(sessionId, token) {
  const baseUrl = 'https://api.scriptix.io/api/v3/speech-to-text/session';
  
  while (true) {
    const response = await fetch(`${baseUrl}/${sessionId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    
    const session = await response.json();
    
    if (session.status === 'completed') {
      console.log('transcription complete!');
      return session;
    } else if (session.status === 'failed') {
      throw new Error(`Transcription failed: ${session.error}`);
    }
    
    console.log(`Status: ${session.status}, waiting...`);
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
  }
}

// Usage
try {
  const session = await pollUntilComplete('abc123def456', YOUR_TOKEN);
  console.log('Document ID:', session.document.id);
} catch (error) {
  console.error('Error:', error.message);
}

Polling with Timeout

async function pollWithTimeout(sessionId, token, timeoutMs = 600000) {
  const startTime = Date.now();
  const pollInterval = 5000; // 5 seconds
  
  while (true) {
    // Check timeout
    if (Date.now() - startTime > timeoutMs) {
      throw new Error('Polling timeout exceeded');
    }
    
    const response = await fetch(
      `https://api.scriptix.io/api/v3/speech-to-text/session/${sessionId}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    const session = await response.json();
    
    if (session.status === 'completed') {
      return session;
    } else if (session.status === 'failed') {
      throw new Error(`Transcription failed: ${session.error}`);
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
}

// Usage with 10-minute timeout
try {
  const session = await pollWithTimeout('abc123def456', YOUR_TOKEN, 600000);
  console.log('Success!', session.document.id);
} catch (error) {
  console.error('Error:', error.message);
}

Python Polling

import time
import requests

def poll_until_complete(session_id, token, timeout=600):
    url = f'https://api.scriptix.io/api/v3/speech-to-text/session/{session_id}'
    headers = {'Authorization': f'Bearer {token}'}
    
    start_time = time.time()
    poll_interval = 5  # seconds
    
    while True:
        # Check timeout
        if time.time() - start_time > timeout:
            raise TimeoutError('Polling timeout exceeded')
        
        response = requests.get(url, headers=headers)
        session = response.json()
        
        if session['status'] == 'completed':
            print('Transcription complete!')
            return session
        elif session['status'] == 'failed':
            raise Exception(f"Transcription failed: {session.get('error')}")
        
        print(f"Status: {session['status']}, waiting...")
        time.sleep(poll_interval)

# Usage
try:
    session = poll_until_complete('abc123def456', YOUR_TOKEN)
    print('Document ID:', session['document']['id'])
except Exception as e:
    print('Error:', str(e))

Polling Best Practices

Recommended Poll Interval

function getPollingInterval(elapsedTime) {
  // Adaptive polling: slower as time progresses
  if (elapsedTime < 60000) {
    return 3000; // 3 seconds for first minute
  } else if (elapsedTime < 300000) {
    return 5000; // 5 seconds for next 4 minutes
  } else {
    return 10000; // 10 seconds after 5 minutes
  }
}

async function pollWithAdaptiveInterval(sessionId, token) {
  const startTime = Date.now();
  
  while (true) {
    const response = await fetch(
      `https://api.scriptix.io/api/v3/speech-to-text/session/${sessionId}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    const session = await response.json();
    
    if (session.status === 'completed') {
      return session;
    } else if (session.status === 'failed') {
      throw new Error(session.error);
    }
    
    const elapsed = Date.now() - startTime;
    const interval = getPollingInterval(elapsed);
    
    await new Promise(resolve => setTimeout(resolve, interval));
  }
}

Avoid Polling Too Frequently

// ❌ Bad: Polling every second (wasteful, may hit rate limits)
setInterval(() => checkStatus(sessionId), 1000);

// ✅ Good: Poll every 5-10 seconds
setInterval(() => checkStatus(sessionId), 5000);

// ✅ Better: Use webhooks instead of polling
uploadWithWebhook(file, 'https://your-app.com/webhook');

Use Webhooks Instead

For production applications, use Webhooks instead of polling:

// Upload with webhook
const response = await uploadFile(file, 'en', {
  webhook_url: 'https://your-app.com/webhooks/transcription'
});

// Webhook receives notification when done
app.post('/webhooks/transcription', (req, res) => {
  const { session_id, status, document } = req.body;
  
  if (status === 'completed') {
    processTranscript(session_id, document.id);
  }
  
  res.sendStatus(200);
});

Error Handling

Failed Session

When status is failed, check the error field:

{
  "id": 12345,
  "session_id": "abc123def456",
  "status": "failed",
  "error": "Audio format could not be decoded. Please check file integrity.",
  "filename": "corrupted.mp3"
}

Common Error Messages:

• "Audio format could not be decoded" - File is corrupted or unsupported format
• "Audio file is too short" - File duration < 1 second
• "Language detection failed" - Audio quality too poor
• "Processing timeout" - Internal issue (contact support)

Handling:

const session = await getSession(sessionId);

if (session.status === 'failed') {
  console.error('transcription failed:', session.error);
  
  if (session.error.includes('format')) {
    console.log('Try converting file to MP3 or WAV');
  } else if (session.error.includes('too short')) {
    console.log('File must be at least 1 second long');
  } else {
    console.log('Contact support with session ID:', session.session_id);
  }
}

Session Not Found

404 Error:

{
  "error": "Not Found",
  "message": "Session not found",
  "error_code": "SESSION_NOT_FOUND"
}

Causes:

• Invalid session ID
• Session deleted
• Session belongs to different organization

Retrieving Multiple Sessions

List All Sessions

curl "https://api.scriptix.io/api/v3/speech-to-text/session?offset=0&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "count": 50,
  "total_results": 150,
  "result": [
    {
      "id": 12345,
      "session_id": "abc123",
      "status": "completed",
      "filename": "meeting.mp3",
      ...
    },
    ...
  ]
}

See Pagination for details.

Filter by Status

curl "https://api.scriptix.io/api/v3/speech-to-text/session?status=completed&offset=0&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter Options:

• status=queued
• status=processing
• status=completed
• status=failed

Next Steps

• Retrieve Results - Download transcript when status is completed
• Webhooks - Avoid polling with automated notifications
• Upload - Upload new files
• Documents API - Manage transcripts

---

Monitor processing! Poll session status to know when your transcript is ready.