/request

Use /request to retrieve information associated with a single $requestID, including

Request processing status.
Request results, including JSON transcript, metadata, and audio files.

To automatically send results to another host or system when transcription and analytics processing is complete, use a folder configured to send results using callbacks. /request supports GET requests only.

Synopsis

GET /request/$org_short/status?requestid=$requestID&token=$token
GET /request/$org_short/summary?requestid=$requestID&token=$token > $output_file.json
GET /request/$org_short/details?requestid=$requestID&token=$token > $output_file.json
GET /request/$org_short/results?requestid=$requestID&token=$token > $output_file.zip

$org_short: Organization short name used to filter the request.
$requestID: UUID for the query's target request.
$token: Authorization token with the required read or write permissions for the request.
$output_file: File path for query output.

Endpoints

/request endpoints accept GET requests for a single $requestID.

/request/$org_short/status

Returns a plain text message with these processing states:

analyzing: Request data has been transcribed, and its transcription data is being analyzed.
done: Transcription and analytics processing is complete. Results for the specified request are ready for callback or download.
error: Something went wrong with the request, and no results will ever be available. Validate the data in the original /transcribe request.
received: Initial /transcribe request file(s) have been received and were queued for ASR transcription.

/request/$org_short/summary

Returns JSON summary data for the specified $requestID with these fields.

time_submit: Timestamp generated when request is initially submitted.
time_complete: Timestamp generated when the request finished processing.
status: Overall request status; identical to the value returned by the /request/$org_short/status endpoint.
processed: Number of files in the request that were processed for transcription.
analyzed: Number of transcripts analyzed for the request.
error: Number of audio files that produced an error when processed or analyzed.
submitted: Number of audio files submitted with the request.

Note: Count information is not provided for fields that are NULL.

/request/$org_short/details

Returns JSON data with the fields described for /request/$org_short/summary along with an additional filedetails array with advanced record details.

The filedetails array contains one object for each audio file in the request. Each object contains these fields.

fullfilename: The name of the file sent with the request.
status: Request processing status.
job_start: Timestamp generated when the request's transcription job began processing.
job_finish: Timestamp generated when the request's transcription job finished processing.
analyze: Timestamp generated when the request's analytics job finished processing.
size: Request's total file size.

/request/$org_short/result

Returns a zip with the results of the specified $requestID. Zip contents depend on these optional boolean query parameters.


Parameter	Examples	Description
json	json=0 json=1 (default)	Include the complete JSON transcript for each request audio file.
mp3	mp3=0 (default) mp3=1	Include the request's transcoded mp3 file(s).
txt	txt=0 (default) txt=1	Include a plain text version of request transcript(s).

Example cURL requests

/request/$org_short/status

curl 'http://example.company.com:3000/request/co1-orgA/status?requestid=$requestID&token=$token' > $output_file

/request/$org_short/summary

curl 'http://example.company.com:3000/request/co1-orgA/summary?requestid=$requestID&token=$token' > $output_file.json

/request/$org_short/details

curl 'http://example.company.com:3000/request/co1-orgA/details?requestid=$requestID&token=$token' > $output_file.json

/request/$org_short/result

curl 'http://example.company.com:3000/request/co1-orgA/result?requestid=$requestID&token=$token&json=1&mp3=1&txt=1' > $output_file.zip