Skip to main content
Deepgram's Docs

Search documentation

Type to search this documentation.

On this pageOverview

Get Project Usage Breakdown

GET https://api.deepgram.com/v1/projects//usage/breakdown

Retrieves the usage breakdown for a specific project, with various filter options by API feature or by groupings. Setting a feature (e.g. diarize) to true includes requests that used that feature, while false excludes requests that used it. Multiple true filters are combined with OR logic, while false filters use AND logic.

Reference: https://developers.deepgram.com/reference/manage/usage/breakdown/get

Authentication

Section titled “Authentication”
  • Authorization header (required) (prefixed with Token ) — Use Authorization: Token <API_KEY> Example: Authorization: Token 12345abcdef

Request

Section titled “Request”

Path parameters

Section titled “Path parameters”
  • project_id (string, required) — The unique identifier of the project

Query parameters

Section titled “Query parameters”
  • start (string, optional) — Start date of the requested date range. Format accepted is YYYY-MM-DD
  • end (string, optional) — End date of the requested date range. Format accepted is YYYY-MM-DD
  • grouping (enum, optional) — Common usage grouping parameters
    • Allowed values: accessor, endpoint, feature_set, models, method, tags, deployment
  • accessor (string, optional) — Filter for requests where a specific accessor was used
  • alternatives (boolean, optional) — Filter for requests where alternatives were used
  • callback_method (boolean, optional) — Filter for requests where callback method was used
  • callback (boolean, optional) — Filter for requests where callback was used
  • channels (boolean, optional) — Filter for requests where channels were used
  • custom_intent_mode (boolean, optional) — Filter for requests where custom intent mode was used
  • custom_intent (boolean, optional) — Filter for requests where custom intent was used
  • custom_topic_mode (boolean, optional) — Filter for requests where custom topic mode was used
  • custom_topic (boolean, optional) — Filter for requests where custom topic was used
  • deployment (enum, optional) — Filter for requests where a specific deployment was used
    • Allowed values: hosted, beta, self-hosted
  • detect_entities (boolean, optional) — Filter for requests where detect entities was used
  • detect_language (boolean, optional) — Filter for requests where detect language was used
  • diarize (boolean, optional) — Filter for requests where diarize was used
  • dictation (boolean, optional) — Filter for requests where dictation was used
  • encoding (boolean, optional) — Filter for requests where encoding was used
  • endpoint (enum, optional) — Filter for requests where a specific endpoint was used
    • Allowed values: listen, read, speak, agent
  • extra (boolean, optional) — Filter for requests where extra was used
  • filler_words (boolean, optional) — Filter for requests where filler words was used
  • intents (boolean, optional) — Filter for requests where intents was used
  • keyterm (boolean, optional) — Filter for requests where keyterm was used
  • keywords (boolean, optional) — Filter for requests where keywords was used
  • language (boolean, optional) — Filter for requests where language was used
  • measurements (boolean, optional) — Filter for requests where measurements were used
  • method (enum, optional) — Filter for requests where a specific method was used
    • Allowed values: sync, async, streaming
  • model (string, optional) — Filter for requests where a specific model uuid was used
  • multichannel (boolean, optional) — Filter for requests where multichannel was used
  • numerals (boolean, optional) — Filter for requests where numerals were used
  • paragraphs (boolean, optional) — Filter for requests where paragraphs were used
  • profanity_filter (boolean, optional) — Filter for requests where profanity filter was used
  • punctuate (boolean, optional) — Filter for requests where punctuate was used
  • redact (boolean, optional) — Filter for requests where redact was used
  • replace (boolean, optional) — Filter for requests where replace was used
  • sample_rate (boolean, optional) — Filter for requests where sample rate was used
  • search (boolean, optional) — Filter for requests where search was used
  • sentiment (boolean, optional) — Filter for requests where sentiment was used
  • smart_format (boolean, optional) — Filter for requests where smart format was used
  • summarize (boolean, optional) — Filter for requests where summarize was used
  • tag (string, optional) — Filter for requests where a specific tag was used
  • topics (boolean, optional) — Filter for requests where topics was used
  • utt_split (boolean, optional) — Filter for requests where utt split was used
  • utterances (boolean, optional) — Filter for requests where utterances was used
  • version (boolean, optional) — Filter for requests where version was used

Response

Section titled “Response”

200

Section titled “200”

Usage breakdown response

  • start (string, required) — Start date of the usage period
  • end (string, required) — End date of the usage period
  • resolution (UsageBreakdownV1ResponseResolution, required)
  • results (list of UsageBreakdownV1ResponseResultsItems, required)

Errors

Section titled “Errors”

400 Bad Request Error

Section titled “400 Bad Request Error”

Invalid Request

  • ErrorResponse

Types

Section titled “Types”

UsageBreakdownV1ResponseResolution

Section titled “UsageBreakdownV1ResponseResolution”
  • units (string, required) — Time unit for the resolution
  • amount (double, required) — Amount of units

UsageBreakdownV1ResponseResultsItems

Section titled “UsageBreakdownV1ResponseResultsItems”
  • hours (float, required) — Audio hours processed
  • total_hours (float, required) — Total hours including all processing
  • agent_hours (float, required) — Agent hours used
  • tokens_in (double, required) — Number of input tokens
  • tokens_out (double, required) — Number of output tokens
  • tts_characters (double, required) — Number of text-to-speech characters processed
  • requests (double, required) — Number of requests
  • grouping (UsageBreakdownV1ResponseResultsItemsGrouping, required)

ErrorResponseLegacyError

Section titled “ErrorResponseLegacyError”
  • err_code (string, optional) — The error code
  • err_msg (string, optional) — The error message
  • request_id (string, optional) — The request ID

ErrorResponseModernError

Section titled “ErrorResponseModernError”
  • category (string, optional) — The category of the error
  • message (string, optional) — A message about the error
  • details (string, optional) — A description of the error
  • request_id (string, optional) — The unique identifier of the request

UsageBreakdownV1ResponseResultsItemsGrouping

Section titled “UsageBreakdownV1ResponseResultsItemsGrouping”
  • start (string, optional) — Start date for this group
  • end (string, optional) — End date for this group
  • accessor (string, optional, nullable) — Optional accessor identifier
  • endpoint (string, optional, nullable) — Optional endpoint identifier
  • feature_set (string, optional, nullable) — Optional feature set identifier
  • models (list of string, optional)
  • method (string, optional, nullable) — Optional method identifier
  • tags (list of string, optional, nullable) — Optional list of tags, null unless grouped by tags.
  • deployment (string, optional, nullable) — Optional deployment identifier

Examples

Section titled “Examples”

Response

JSON
{
  "start": "2025-01-16",
  "end": "2025-01-23",
  "resolution": {
    "units": "day",
    "amount": 1
  },
  "results": [
    {
      "hours": 1619.7242069444444,
      "total_hours": 1621.7395791666668,
      "agent_hours": 41.33564388888889,
      "tokens_in": 0,
      "tokens_out": 0,
      "tts_characters": 9158866,
      "requests": 373381,
      "grouping": {
        "start": "2025-01-16",
        "end": "2025-01-16",
        "accessor": "123456789012345678901234",
        "endpoint": "listen",
        "feature_set": "punctuate",
        "models": [
          "Nova-2"
        ],
        "method": "async",
        "tags": [
          "tag1",
          "tag2"
        ],
        "deployment": "self-hosted"
      }
    }
  ]
}

SDK Code

Python
import requests

url = "https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown"

querystring = {"accessor":"12345678-1234-1234-1234-123456789012","alternatives":"true","callback":"true","callback_method":"true","channels":"true","custom_intent":"true","custom_intent_mode":"true","custom_topic":"true","custom_topic_mode":"true","deployment":"hosted","detect_entities":"true","detect_language":"true","diarize":"true","dictation":"true","encoding":"true","endpoint":"listen","extra":"true","filler_words":"true","intents":"true","keyterm":"true","keywords":"true","language":"true","measurements":"true","method":"async","model":"6f548761-c9c0-429a-9315-11a1d28499c8","multichannel":"true","numerals":"true","paragraphs":"true","profanity_filter":"true","punctuate":"true","redact":"true","replace":"true","search":"true","sentiment":"true","smart_format":"true","summarize":"true","tag":"tag1","topics":"true","utt_split":"true","utterances":"true","version":"true"}

headers = {"Authorization": "Token <apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
JavaScript
const url = 'https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true';
const options = {method: 'GET', headers: {Authorization: 'Token <apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Token <apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
Ruby
require 'uri'
require 'net/http'

url = URI("https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Token <apiKey>'

response = http.request(request)
puts response.read_body
Java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true")
  .header("Authorization", "Token <apiKey>")
  .asString();
PHP
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true', [
  'headers' => [
    'Authorization' => 'Token <apiKey>',
  ],
]);

echo $response->getBody();
C#
using RestSharp;

var client = new RestClient("https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Token <apiKey>");
IRestResponse response = client.Execute(request);
Swift
import Foundation

let headers = ["Authorization": "Token <apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.deepgram.com/v1/projects/123456-7890-1234-5678-901234/usage/breakdown?accessor=12345678-1234-1234-1234-123456789012&alternatives=true&callback=true&callback_method=true&channels=true&custom_intent=true&custom_intent_mode=true&custom_topic=true&custom_topic_mode=true&deployment=hosted&detect_entities=true&detect_language=true&diarize=true&dictation=true&encoding=true&endpoint=listen&extra=true&filler_words=true&intents=true&keyterm=true&keywords=true&language=true&measurements=true&method=async&model=6f548761-c9c0-429a-9315-11a1d28499c8&multichannel=true&numerals=true&paragraphs=true&profanity_filter=true&punctuate=true&redact=true&replace=true&search=true&sentiment=true&smart_format=true&summarize=true&tag=tag1&topics=true&utt_split=true&utterances=true&version=true")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu