Usage

The deepgram.usage object provides access to the usage endpoints of the Deepgram API. Each request is project based and will require a project_id.

Requests by Project

Retrieves transcription requests for a project based on the provided options.

Requests by Project Parameters

Parameter	Type	Description
project_id	String	A unique identifier for the project to retrieve usage for
options	Object	Parameters to filter requests. See below.

Requests by Project Options

{
  // The time to retrieve requests made since
  // Example: "2020-01-01T00:00:00+00:00"
  start?: String,
  // The time to retrieve requests made until
  // Example: "2021-01-01T00:00:00+00:00"
  end?: String,
  // Page of requests to return
  // Defaults to 0
  page?: Number,
  // Number of requests to return per page
  // Defaults to 10. Maximum of 100
  limit?: Number,
  // Filter by succeeded or failed requests
  // By default, all requests are returned
  status?: 'succeeded' | 'failed'
}

Requests by Project Example Request

const response = await deepgram.usage.listRequests(PROJECT_ID, {
    limit: 10,
    // other options are available
});

Requests by Project Response

{
  page: Number,
  limit: Number,
  requests?: [
    {
      request_id: String;
      created: String;
      path: String;
      accessor: String;
      response?:  {
        details: {
          usd: Number;
          duration: Number;
          total_audio: Number;
          channels: Number;
          streams: Number;
          model: String;
          method: String;
          tags: String[];
          features: String[];
          config: {
            multichannel?: Boolean;
            interim_results?: Boolean;
            punctuate?: Boolean;
            ner?: Boolean;
            utterances?: Boolean;
            replace?: Boolean;
            profanity_filter?: Boolean;
            keywords?: Boolean;
            diarize?: Boolean;
            search?: Boolean;
            redact?: Boolean;
            alternatives?: Boolean;
            numerals?: Boolean;
          };
        }
      }, ||
      {
        message?: String;
      },
      callback?: {
        code: Number;
        completed: String;
      },
    },
  ];
}

Get Request

Retrieves a specific transcription request for a project based on the provided projectId and requestId.

Get Request Parameters

Parameter	Type	Description
project_id	String	A unique identifier for the project to retrieve usage for
request_id	String	Unique identifier of the request to retrieve

Get Request Example Request

const response = await deepgram.usage.getRequest(PROJECT_ID, REQUEST_ID);

Get Request Response

{
  request_id: String;
  created: String;
  path: String;
  accessor: String;
  response?:  {
    details: {
      usd: Number;
      duration: Number;
      total_audio: Number;
      channels: Number;
      streams: Number;
      model: String;
      method: String;
      tags: String[];
      features: String[];
      config: {
        multichannel?: Boolean;
        interim_results?: Boolean;
        punctuate?: Boolean;
        ner?: Boolean;
        utterances?: Boolean;
        replace?: Boolean;
        profanity_filter?: Boolean;
        keywords?: Boolean;
        diarize?: Boolean;
        search?: Boolean;
        redact?: Boolean;
        alternatives?: Boolean;
        numerals?: Boolean;
      };
    }
  }, ||
  {
    message?: String;
  },
  callback?: {
    code: Number;
    completed: String;
  }
}

Get Usage by Project

Retrieves aggregated usage data for a project based on the provided options.

Get Usage by Project Parameters

Parameter	Type	Description
project_id	String	A unique identifier for the project to retrieve usage for
options	Object	Parameters to filter requests. See below.

Get Usage by Project Options

{
  // The time to retrieve requests made since
  // Example: "2020-01-01T00:00:00+00:00"
  start?: String,
  // The time to retrieve requests made until
  // Example: "2021-01-01T00:00:00+00:00"
  end?: String,
  // Specific identifer for a request
  accessor?: String,
  // Array of tags used in requests
  tag?: String[],
  // Filter requests by method
  method?: "sync" | "async" | "streaming",
  // Filter requests by model used
  model?: String,
  // Filter only requests using multichannel feature
  multichannel?: Boolean,
  // Filter only requests using interim results feature
  interim_results?: Boolean,
  // Filter only requests using the punctuation feature
  punctuate?: Boolean,
  // Filter only requests using ner feature
  ner?: Boolean,
  // Filter only requests using utterances feature
  utterances?: Boolean,
  // Filter only requests using replace feature
  replace?: Boolean,
  // Filter only requests using profanity_filter feature
  profanity_filter?: Boolean,
  // Filter only requests using keywords feature
  keywords?: Boolean,
  // Filter only requests using diarization feature
  diarize?: Boolean,
  // Filter only requests using search feature
  search?: Boolean,
  // Filter only requests using redact feature
  redact?: Boolean,
  // Filter only requests using alternatives feature
  alternatives?: Boolean,
  // Filter only requests using numerals feature
  numerals?: Boolean
}

Get Usage by Project Example Request

const response = await deepgram.usage.getUsage(PROJECT_ID, {
    start: "2020-01-01T00:00:00+00:00",
    // other options are available
});

Get Usage by Project Response

{
  start: String,
  end: String,
  resolution: {
    units: String,
    amount: Number
  };
  results: [
    {
      start: String,
      end: String,
      hours: Number,
      requests: Number
    }
  ];
}

Get Fields

Retrieves features used by the provided project_id based on the provided options.

Get Fields Parameters

Parameter	Type	Description
project_id	String	A unique identifier for the project to retrieve fields used for
options	Object	Parameters to filter requests. See below.

Get Fields Options

{
  // The time to retrieve requests made since
  // Example: "2020-01-01T00:00:00+00:00"
  start?: String,
  // The time to retrieve requests made until
  // Example: "2021-01-01T00:00:00+00:00"
  end?: String
}

Get Fields Example Request

const response = await deepgram.usage.getFields(PROJECT_ID, {
    start: "2020-01-01T00:00:00+00:00",
    // other options are available
});

Get Fields Response

{
  tags: String[],
  models: String[],
  processing_methods: String[],
  languages: String[],
  features: String[]
}