> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.deepgram.com/docs/text-topic-detection/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.deepgram.com/_mcp/server. # Topic Detection Deepgram API Playground Try this feature out in our API Playground. \ `topics` *boolean*   Default: `false` English (all available regions) Topic Detection accepts an input text, divides it into a list of segments comprised of sections of the text, and identifies key topics found within each segment. **`JSON`** ```json JSON "results": { "topics": { "segments": [ { "text": "Hi I'm calling to get a refund on my recent purchase. Sure I'd be happy to help you with that. What was the number for you order?", "start_word": 0, "end_word": 26, "topics": [ { "topic": "Refund", "confidence_score": 0.91318 }, { "topic": "Order Number", "confidence_score": 0.95342 } ] }, { "text": "Ok thanks for that. It looks like you made this purchase online, is that correct? Yes I ordered this online on your website a few days ago.", "start_word": 45, "end_word": 72, "topics": [ { "topic": "Online Transacation", "confidence_score": 0.741929 } ] } ] } } ``` The list of topics that can be identified are not a fixed list; this TSLM powered feature is able to generate topics based on the context of the language content in the text. You may also choose to use the optional `custom-topic` parameter to provide a custom topic you want detected if present within the provided text. ## Enable Feature To enable Topic Detection, use the following parameter in the query string when you call Deepgram’s `/read` endpoint: `topics=true` ### Basic Text Request To analyze text from a file on your computer, run the following curl command in a terminal or your favorite API client. **`cURL`** ```bash cURL curl -vX POST \ -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "YOUR_TEXT_INPUT"}' \ "https://api.deepgram.com/v1/read?topics=true&language=en" ``` > **Warning** > > Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](https://console.deepgram.com/signup?jump=keys). ### Basic URL Request To analyze text from a hosted file, run the following curl command in a terminal or your favorite API client. (Try testing it out with the hosted file [https://static.deepgram.com/examples/aura.txt](https://static.deepgram.com/examples/aura.txt)) ### Custom Topics Request To tell the model to only return topics from your own custom list of topics, add `custom_topic_mode=strict` and `custom_topic=` followed by the list of topics. (Use the URL encoding`%20` to represent a space between each word in the list.) If you want to return your own custom list of topics *in addition* to Deegpram's list of topics, set `custom_topic_mode=extended` and add your custom list. **`cURL`** ```bash cURL curl -vX POST \ -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "YOUR_TEXT_INPUT"}' \ "https://api.deepgram.com/v1/read?topics=true&language=en&custom_topic_mode=strict&custom_topic=refund&custom_topic=online_transaction&custom_topic=Order%20Number" ``` > **Info** > > Read our [Text Intelligence Getting Started guide](/docs/text-intelligence), which will walk you through making a basic text request and a basic URL request with the Deepgram SDKs. ### Query Parameters | Parameter | Value | Type | Description | | ------------------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `topics` | `true` | boolean | Enables Topic Detection | | `language` | `en` | string | The language of your input text (Only English is supported at this time.) | | `custom_topic` | ex: `animals` | string | Optional. A custom topic you want the model to detect within your input text if present. Submit up to 100. | | `custom_topic_mode` | `extended`, `strict` | string | Optional. 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. | ## Analyze Response When the file is finished processing, you’ll receive a JSON response that has the following basic structure: **`JSON`** ```json JSON { "metadata": { "request_id": "c313ae16-2c3b-4c51-87a6-920a8aa1d899", "created": "2023-11-28T01:44:27.083Z", "language": "en", "topics_info": { "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc", "input_tokens": 22, "output_tokens": 4 } }, "results": { "topics": { "segments": [ { "text": "Hi I'm calling to get a refund on my recent purchase. Sure I'd be happy to help you with that. What was the number for you order?", "start_word": 0, "end_word": 26, "topics": [ { "topic": "Refund", "confidence_score": 0.91318 }, { "topic": "Order Number", "confidence_score": 0.95342 } ] }, { "text": "Ok thanks for that. It looks like you made this purchase online, is that correct? Yes I ordered this online on your website a few days ago.", "start_word": 45, "end_word": 72, "topics": [{ "topic": "Online Transacation", "confidence_score": 0.741929 }] } ] } } } ``` The response object values for `topics` are: * `segments`: The list of segments of text identified by the model as containing notable topics. * `topic`: The name of the topic detected by the model. * `confidence_score`: a floating point from 0 to 1 representing the models confidence in this prediction. ## API Error Responses ### Unsupported Language **Status** 400 If you request Topic Detection with an unsupported language by specifying a language code such as `topics=true&language=es` or `topics=true&detect_language=true` where the detected language is unsupported, you will get the error message below. **`JSON`** ```json JSON { "err_code":"INVALID_QUERY_PARAMETER", "err_msg":"Request specified unsupported language: . Only English is supported.", "request_id":"XXXX" } ``` ### Token Limit Exceeded **Status** 400 If the request's input length exceeded the 150k token rate limit per request, you will get the error message below. **`JSON`** ```json JSON { "err_code": "TOKEN_LIMIT_EXCEEDED", "err_msg": "Text input for currently supports up to 150K tokens. Please revise your text input to fit within the defined token limit. For more information, please visit our API documentation.", "request_id": "XXXX" } ``` ### Missing Query Parameter **Status** 400 If the request sent contained only the feature parameter (`topics`) but not the `language` parameter, you will receive this error. **`JSON`** ```json JSON { "err_code":"INVALID_QUERY_PARAMETER", "err_msg":"Failed to deserialize query parameters: missing field `language`", "request_id":"XXX" } ``` > Topic Detection detects topics throughout the input text.