# Topic Detection :::card{title="Deepgram API Playground" href="https://playground.deepgram.com/?endpoint=read&topics=true&language=en"} 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 "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. ```bash 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" ``` :::callout{intent="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) ### 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. ```bash 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" ``` :::callout{intent="info"} Read our [Text Intelligence Getting Started guide](/guides/self-hosted-deployments-6-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 { "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 { "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 { "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 { "err_code":"INVALID_QUERY_PARAMETER", "err_msg":"Failed to deserialize query parameters: missing field `language`", "request_id":"XXX" } ``` ## Related pages - [Getting Started](./self-hosted-deployments-6-text-intelligence.md) - [Feature Overview](./self-hosted-deployments-6-text-intelligence-feature-overview.md) - [Template Apps](./self-hosted-deployments-6-text-intelligence-template-apps.md) - [Intent Recognition](./self-hosted-deployments-6-text-intention-recognition.md) - [Sentiment Analysis](./self-hosted-deployments-6-text-sentiment-analysis.md) - [Summarization](./self-hosted-deployments-6-text-summarization.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.