Usage
Deepgram tracks requests made to Deepgram services and associates usage information with Projects.
Get All Requests
Generates a list of requests sent to the Deepgram API for the specified project over a given time range. Uses pagination to limit the number of results returned.
Path Parameters
project_id: uuid
Unique identifier of the project for which you want to retrieve requests.
Query Parameters
start: string
Start date of the requested date range. Format is YYYY-MM-DD. Defaults to the time of your first request.
If no time zone is specified, defaults to Coordinated Universal Time (UTC).
end: string
End date of the requested date range. Format is YYYY-MM-DD. Defaults to the current time.
If no time zone is specified, defaults to Coordinated Universal Time (UTC).
limit: integer
Number of results to return per page.
Default: 10
status: string
Status of requests to return. Enables you to filter requests depending on whether they have succeeded or failed. If not specified, returns requests with all statuses.
Default: null
Possible values: null
, succeeded
OR failed
Responses
Status | Description |
---|---|
200 Success | Requests found. Requests will be returned in descending order based on creation time (newest first). |
Response Schema
page: integer
Page number that should be returned. Used for pagination.
limit: integer
Number of results to return per page. Used for pagination.
requests: array
request_id: uuid
Unique identifier of request.
created: string
Date/time when request was created.
path: string
Path of endpoint to which request was submitted.
api_key_id: uuid
Unique identifier of the API Key with which the request was submitted.
response: object
Response generated by the request. If a response has not yet been generated, this object will be empty.
details: object
If the request failed, then this object will be replaced by an optional
message
field that may contain an error message.usd: number
Cost of the request in USD, if project is non-contract and the requesting account has appropriate permissions.
duration: number
Length of time (in hours) of audio processed in the request.
total_audio: number
Number of audio files processed in the request.
channels: integer
Number of channels in the audio associated with the request.
streams: integer
Number of audio streams associated with the request.
models: array
Array of models applied when running the request.
method: string
Processing method used when running the request.
tags: array
Array of tags applied when running the request.
features: array
Array of features used when running the request.
config: object
Configuration used when running the request.
alternatives: integer
Requested maximum number of transcript alternatives to return. If no alternative value was submitted, this item will not be returned.
diarize: boolean
Indicates whether diarization was requested. If not requested, this item will not be returned.
keywords: array
Array of keywords associated with the request. If no keywords were submitted, this item will not be returned.
topics: array
Array of topics associated with the request. If no topics were identified, this item will not be returned.
language: string
Language associated with the request. If no languages were submitted, this item will not be returned.
model: string
Model associated with the request. If no models were submitted, this item will not be returned.
multichannel: boolean
Indicates whether multichannel processing was requested. If not requested, this item will not be returned.
ner: boolean
Indicates whether named-entity recognition (NER) was requested. If not requested, this item will not be returned.
numerals: boolean
Indicates whether numeral conversion was requested. If not requested, this item will not be returned.
profanity_filter: boolean
Indicates whether filtering profanity was requested. If not requested, this item will not be returned.
punctuate: boolean
Indicates whether punctuation was requested. If not requested, this item will not be returned.
redact: array
Indicates whether redaction was requested. If not requested, this item will not be returned.
search: array
Array of seach terms associated with the request. If no search terms were submitted, this item will not be returned.
utterances: boolean
Indicates whether utterance segmentation was requested. If not requested, this item will not be returned.
code: integer
completed: string
callback: object
Only exists if a callback was included in the request. If a callback was included in the request, but the request has not completed yet, then this object will exist, but it will be empty. The
attempts
item will exist only while the request has not completed. Thecompleted
item will exist only after the request completes.attempts: integer
code: integer
completed: string
Get Request
Retrieves the details of the specified request sent to the Deepgram API for the specified project.
Path Parameters
project_id: uuid
Unique identifier of the project for which you want to retrieve the specified request.
request_id: uuid
Unique identifier of the request that you want to retrieve.
Responses
Status | Description |
---|---|
200 Success | Request found. |
404 Not Found | A request with the specified request ID in the specified project was not found. |
Response Schema
request_id: uuid
Unique identifier of request.
created: string
Date and time when request was created.
path: string
Path of endpoint to which request was submitted.
api_key_id: uuid
Unique identifier of the API Key with which the request was submitted.
response: object
Response generated by the request. If a response has not yet been generated, this object will be empty.
details: object
If the request failed, then this object will be replaced by an optional
message
field that may contain an error message.usd: number
Cost of the request in USD, if project is non-contract and the requesting account has appropriate permissions.
duration: number
Length of time (in hours) of audio processed in the request.
total_audio: number
Number of audio files processed in the request.
channels: integer
Number of channels in the audio associated with the request.
streams: integer
Number of audio streams associated with the request.
models: array
Array of models applied when running the request.
method: string
Processing method used when running the request.
tags: array
Array of tags applied when running the request.
features: array
Array of features used when running the request.
config: object
Configuration used when running the request.
alternatives: integer
Requested maximum number of transcript alternatives to return. If no alternative value was submitted, this item will not be returned.
diarize: boolean
Indicates whether diarization was requested. If not requested, this item will not be returned.
keywords: array
Array of keywords associated with the request. If no keywords were submitted, this item will not be returned.
topics: array
Array of topics associated with the request. If no topics were identified, this item will not be returned.
language: string
Language associated with the request. If no languages were submitted, this item will not be returned.
model: string
Model associated with the request. If no models were submitted, this item will not be returned.
multichannel: boolean
Indicates whether multichannel processing was requested. If not requested, this item will not be returned.
ner: boolean
Indicates whether named-entity recognition (NER) was requested. If not requested, this item will not be returned.
numerals: boolean
Indicates whether numeral conversion was requested. If not requested, this item will not be returned.
profanity_filter: boolean
Indicates whether filtering profanity was requested. If not requested, this item will not be returned.
punctuate: boolean
Indicates whether punctuation was requested. If not requested, this item will not be returned.
redact: array
Indicates whether redaction was requested. If not requested, this item will not be returned.
search: array
Array of seach terms associated with the request. If no search terms were submitted, this item will not be returned.
utterances: boolean
Indicates whether utterance segmentation was requested. If not requested, this item will not be returned.
code: integer
completed: string
callback: object
Only exists if a callback was included in the request. If a callback was included in the request, but the request has not been attempted yet, then this object will exist, but it will be empty. The
attempts
item will exist only while the request has not completed. Thecompleted
item will exist only after the request completes.attempts: integer
code: integer
completed: string
Summarize Usage
Retrieves a summary of usage statistics. You can specify a date range.
Path Parameters
project_id: uuid
Unique identifier of the project for which you want to summarize usage.
Query Parameters
start: string
Start date of the requested date range. Format: YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC. Defaults to the date of your first request.
end: string
End date of the requested date range. Format is YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC. Defaults to the current date.
accessor: string
Limits results to requests made using the API key corresponding to the given accessor. If not specified, returns requests made using all API keys. To include multiple API Keys, send multiple instances in query string (e.g., accessor=2ed1307e-14f2-48a2-b996-97ea009cfa4e&accessor=1dc0296d-03e1-37z1-1885-86dz998bez3d).
tag: string
Limits results to requests associated with the specified tag. If not specified, returns requests with all tags. To include multiple tags, send multiple instances in query string (e.g., tag=dev&tag=production).
method: string
Limits results to requests processed using the specified method. If not specified, returns requests with all processing methods. To include multiple methods, send multiple instances in query string (e.g., method=sync&method=streaming).
Possible values include:
sync
async
streaming
Possible values: sync
, async
OR streaming
model: string
Limits results to requests run with the specified model UUID applied. If not specified, returns requests with all models. To include multiple models, send multiple instances in query string (e.g., model=4899aa60-f723-4517-9815-2042acc12a82&model=125125fb-e391-458e-a227-a60d6426f5d6).
multichannel: boolean
Limits results to requests that include the multichannel
feature.
interim_results: boolean
Limits results to requests that include the interim_results
feature.
punctuate: boolean
Limits results to requests that include the punctuate
feature.
ner: boolean
Limits results to requests that include the ner
feature.
utterances: boolean
Limits results to requests that include the utterances
feature.
replace: boolean
Limits results to requests that include the replace
feature.
profanity_filter: boolean
Limits results to requests that include the profanity_filter
feature.
keywords: boolean
Limits results to requests that include the keywords
feature.
detect_topics: boolean
Limits results to requests that include the detect_topics
feature.
diarize: boolean
Limits results to requests that include the diarize
feature.
search: boolean
Limits results to requests that include the search
feature.
redact: boolean
Limits results to requests that include the redact
feature.
alternatives: boolean
Limits results to requests that include the alternatives
feature.
numerals: boolean
Limits results to requests that include the numerals
feature.
Responses
Status | Description |
---|---|
200 Success | Usage statistics found. |
404 Not Found | Usage statistics for the requested date range in the specified project were not found. |
Response Schema
start: string
Start date submitted for included requests.
end: string
End date submitted for included requests.
resolution: object
units: string
Units of resolution amount. For example,
days
.amount: integer
Number of resolution units.
results: array
Array of Result objects, one for each day within the date range that has associated requests.
start: string
Start date of included requests.
end: integer
End date of included requests.
hours: number
Length of time (in hours) of audio submitted in included requests.
total_hours: number
Length of time (in hours) of audio processed in included requests. For example, if submitted audio is multichannel,
total_hours
processed will be greater thanhours
submitted because multiple channels are processed separately.requests: integer
Number of included requests.
Get Fields
Lists the features, models, tags, languages, and processing method used for requests in the specified project. You can specify a time range.
Path Parameters
project_id: uuid
Unique identifier of the project for which you want to retrieve fields.
Query Parameters
start: string
Start date of the requested date range. Format is YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC.
Defaults to the date of your first request.
end: string
End date of the requested date range. Format is YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC.
Defaults to the current date.
Responses
Status | Description |
---|---|
200 Success | Request fields found. |
Response Schema
tags: array
Array of included tags.
models: array
Array of included models.
processing_methods: array
Array of processing methods.
Possible values:
sync
,async
ORstreaming
languages: array
Array of included languages.
features: array
Array of included features.
Possible values:
multichannel
,interim_results
,punctuate
,ner
,utterances
,replace
,profanity_filter
,keywords
,detect_topics
,diarize
,search
,redact
,alternatives
ORnumerals