Analyze text content | Deepgram's Docs

POST/v1/readAnalyze text content

Analyze text content using Deepgrams text analysis API

Parameters

callbackstringquery

URL to which we'll make the callback request

callback_methodstringquery

HTTP method by which the callback request will be made

one of "POST", "PUT"

one of "POST", "PUT" · default "POST"

sentimentbooleanquery

Recognizes the sentiment throughout a transcript or text

default false

summarizevaluequery

Summarize content. For Listen API, supports string version option. For Read API, accepts boolean only.

oneOf · 2 options

Option 1stringV1ReadPostParametersSummarize0

V1ReadPostParametersSummarize0

one of "v2"

Option 2boolean

default false

tagvaluequery

Label your requests for the purpose of identification during usage reporting

oneOf · 2 options

Option 1string

Option 2array of string

topicsbooleanquery

Detect topics throughout a transcript or text

default false

custom_topicvaluequery

Custom topics you want the model to detect within your input audio or text if present Submit up to `100`.

oneOf · 2 options

Option 1string

Option 2array of string

custom_topic_modestringquery

Sets how the model will interpret strings submitted to the `custom_topic` param. When `strict`, the model will only return topics submitted using the `custom_topic` param. When `extended`, the model will return its own detected topics in addition to those submitted using the `custom_topic` param

one of "extended", "strict"

one of "extended", "strict" · default "extended"

intentsbooleanquery

Recognizes speaker intent throughout a transcript or text

default false

custom_intentvaluequery

Custom intents you want the model to detect within your input audio if present

oneOf · 2 options

Option 1string

Option 2array of string

custom_intent_modestringquery

Sets how the model will interpret intents submitted to the `custom_intent` param. When `strict`, the model will only return intents submitted using the `custom_intent` param. When `extended`, the model will return its own detected intents in the `custom_intent` param.

one of "extended", "strict"

one of "extended", "strict" · default "extended"

languagestringquery

The [BCP-47 language tag](https://tools.ietf.org/html/bcp47) that hints at the primary spoken language. Depending on the Model and API endpoint you choose only certain languages are available

default "en"

Request body

Analyze a text file

application/json

valueReadV1Request

ReadV1Request

oneOf · 2 options

Option 1objectReadV1RequestUrl

ReadV1RequestUrl

urlstring · urirequired

A URL pointing to the text source

Option 2objectReadV1RequestText

ReadV1RequestText

textstringrequired

The plain text to analyze

Example request

{
  "url": "https://example.com"
}

Responses

objectReadV1Response

ReadV1Response

The standard text response

metadataobjectrequired

Show child attributes

metadataobject

Show child attributes

createdstring · date-time

intents_infoobject

Show child attributes

input_tokensinteger

model_uuidstring · uuid

output_tokensinteger

languagestring

request_idstring · uuid

sentiment_infoobject

Show child attributes

input_tokensinteger

model_uuidstring · uuid

output_tokensinteger

summary_infoobject

Show child attributes

input_tokensinteger

model_uuidstring · uuid

output_tokensinteger

topics_infoobject

Show child attributes

input_tokensinteger

model_uuidstring · uuid

output_tokensinteger

resultsobjectrequired

Show child attributes

intentsobject

Output whenever `intents=true` is used

Show child attributes

segmentsarray of object

Show child attributes

Show array items

end_wordnumber · double

intentsarray of object

Show child attributes

Show array items

confidence_scorestring

intentstring

start_wordnumber · double

textstring

sentimentsobject

Output whenever `sentiment=true` is used

Show child attributes

averageobject

Show child attributes

sentimentstring

sentiment_scorenumber · double

segmentsarray of object

Show child attributes

Show array items

end_wordnumber · double

sentimentstring

sentiment_scorenumber · double

start_wordnumber · double

textstring

summaryobject

Output whenever `summary=true` is used

Show child attributes

resultsobject

Show child attributes

summaryobject

Show child attributes

textstring

topicsobject

Output whenever `topics=true` is used

Show child attributes

segmentsarray of object

Show child attributes

Show array items

end_wordnumber · double

start_wordnumber · double

textstring

topicsarray of object

Show child attributes

Show array items

confidence_scorestring

topicstring

Example response

{
  "metadata": {
    "metadata": {
      "created": "2026-06-09T00:00:00Z",
      "intents_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      },
      "language": "string",
      "request_id": "00000000-0000-0000-0000-000000000000",
      "sentiment_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      },
      "summary_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      },
      "topics_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      }
    }
  },
  "results": {
    "intents": {
      "segments": [
        {
          "end_word": 0,
          "intents": [
            {
              "confidence_score": "string",
              "intent": "string"
            }
          ],
          "start_word": 0,
          "text": "string"
        }
      ]
    },
    "sentiments": {
      "average": {
        "sentiment": "string",
        "sentiment_score": 0
      },
      "segments": [
        {
          "end_word": 0,
          "sentiment": "string",
          "sentiment_score": 0,
          "start_word": 0,
          "text": "string"
        }
      ]
    },
    "summary": {
      "results": {
        "summary": {
          "text": "string"
        }
      }
    },
    "topics": {
      "segments": [
        {
          "end_word": 0,
          "start_word": 0,
          "text": "string",
          "topics": [
            {
              "confidence_score": "string",
              "topic": "string"
            }
          ]
        }
      ]
    }
  }
}

valueErrorResponse

ErrorResponse

oneOf · 3 options

Option 1stringErrorResponseTextError

ErrorResponseTextError

Option 2objectErrorResponseLegacyError

ErrorResponseLegacyError

err_codestring

The error code

err_msgstring

The error message

request_idstring

The request ID

Option 3objectErrorResponseModernError

ErrorResponseModernError

categorystring

The category of the error

detailsstring

A description of the error

messagestring

A message about the error

request_idstring

The unique identifier of the request

Example response

{
  "err_code": "string",
  "err_msg": "string",
  "request_id": "string"
}

Examples

callbackquery parameter

callback_methodquery parameter

sentimentquery parameter

summarizequery parameter

tagquery parameter

topicsquery parameter

custom_topicquery parameter

custom_topic_modequery parameter

intentsquery parameter

custom_intentquery parameter

custom_intent_modequery parameter

languagequery parameter

curl -X POST 'https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

const response = await fetch('https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"url":"https://example.com"}),
});
const data = await response.json();

const response = await fetch('https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"url\":\"https://example.com\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false",
    headers={"Content-Type": "application/json"},
    data='{"url":"https://example.com"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"url":"https://example.com"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"url\":\"https://example.com\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"url\":\"https://example.com\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"url\":\"https://example.com\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://agent.deepgram.com/v1/read?callback=string&callback_method=POST&custom_intent=string&custom_intent_mode=extended&custom_topic=string&custom_topic_mode=extended&intents=false&language=en&sentiment=false&summarize=v2&tag=string&topics=false");
request.Content = new StringContent("{\"url\":\"https://example.com\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "metadata": {
    "metadata": {
      "created": "2026-06-09T00:00:00Z",
      "intents_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      },
      "language": "string",
      "request_id": "00000000-0000-0000-0000-000000000000",
      "sentiment_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      },
      "summary_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      },
      "topics_info": {
        "input_tokens": 0,
        "model_uuid": "00000000-0000-0000-0000-000000000000",
        "output_tokens": 0
      }
    }
  },
  "results": {
    "intents": {
      "segments": [
        {
          "end_word": 0,
          "intents": [
            {
              "confidence_score": "string",
              "intent": "string"
            }
          ],
          "start_word": 0,
          "text": "string"
        }
      ]
    },
    "sentiments": {
      "average": {
        "sentiment": "string",
        "sentiment_score": 0
      },
      "segments": [
        {
          "end_word": 0,
          "sentiment": "string",
          "sentiment_score": 0,
          "start_word": 0,
          "text": "string"
        }
      ]
    },
    "summary": {
      "results": {
        "summary": {
          "text": "string"
        }
      }
    },
    "topics": {
      "segments": [
        {
          "end_word": 0,
          "start_word": 0,
          "text": "string",
          "topics": [
            {
              "confidence_score": "string",
              "topic": "string"
            }
          ]
        }
      ]
    }
  }
}

{
  "err_code": "string",
  "err_msg": "string",
  "request_id": "string"
}