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. The completed item will exist only after the request completes.

      • attempts: integer

      • code: integer

      • completed: string

endpoint
Get All Requests
Response

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. The completed item will exist only after the request completes.

    • attempts: integer

    • code: integer

    • completed: string

endpoint
Get Request
Response

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 than hours submitted because multiple channels are processed separately.

    • requests: integer

      Number of included requests.

endpoint
Summarize Usage
Response

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 OR streaming

  • 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 OR numerals

endpoint
Get Fields
Response

Share your feedback

Thank you! Can you tell us what you liked about it? (Optional)

Thank you. What could we have done better? (Optional)

We may also want to contact you with updates or questions related to your feedback and our product. If don't mind, you can optionally leave your email address along with your comments.

Thank you!

We appreciate your response.