{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "DataForSEO Ai Optimization API Schemas", "definitions": { "AiOptimizationChatGptLlmScraperLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "BaseResponseInfo": { "properties": { "version": { "type": "string", "description": "the current version of the API", "nullable": true }, "status_code": { "type": "integer", "description": "general status code\nyou can find the full list of the response codes here", "nullable": true }, "status_message": { "type": "string", "description": "general informational message\nyou can find the full list of general informational messages here", "nullable": true }, "time": { "type": "string", "description": "total execution time, seconds", "nullable": true }, "cost": { "type": "number", "description": "total tasks cost, USD", "format": "double", "nullable": true }, "tasks_count": { "type": "integer", "description": "the number of tasks in the tasks array", "format": "int64", "nullable": true }, "tasks_error": { "type": "integer", "description": "the number of tasks in the tasks array returned with an error", "format": "int64", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "BaseResponseTaskInfo": { "properties": { "id": { "type": "string", "description": "task identifier\nunique task identifier in our system in the UUID format", "nullable": true }, "status_code": { "type": "integer", "description": "status code of the task\ngenerated by DataForSEO, can be within the following range: 10000-60000\nyou can find the full list of the response codes here", "nullable": true }, "status_message": { "type": "string", "description": "informational message of the task\nyou can find the full list of general informational messages here", "nullable": true }, "time": { "type": "string", "description": "execution time, seconds", "nullable": true }, "cost": { "type": "number", "description": "total tasks cost, USD", "format": "double", "nullable": true }, "result_count": { "type": "integer", "description": "number of elements in the result array", "format": "int64", "nullable": true }, "path": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "URL path", "nullable": true }, "data": { "type": "object", "additionalProperties": { "type": "object", "nullable": true }, "description": "contains the same parameters that you specified in the POST request", "nullable": true } } }, "AiOptimizationChatGptLlmResponsesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesLiveResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "description": "number of reasoning tokenstotal count of tokens used to generate reasoning content", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was used", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "BaseAiOptimizationLlmResponseElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "reasoning": "#/components/schemas/ReasoningAiOptimizationLlmResponseElementItem", "message": "#/components/schemas/MessageAiOptimizationLlmResponseElementItem" } } }, "AiOptimizationGeminiLlmResponsesTaskPostRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value: 1;maximum value: 4096;default value: 2048;Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limitNote #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse lower values make output more focusedminimum value: 0maximum value: 2default value: 1.3", "nullable": true }, "top_p": { "type": "number", "description": "diversity of the AI responseoptional field controls diversity of the response by limiting token selectionminimum value: 0maximum value: 1 default value: 0.9", "nullable": true }, "web_search": { "type": "boolean", "description": "enable web search for current informationoptional fieldwhen enabled, the AI model can access and cite current web information;Note: refer to the Models endpoint for a list of models that support web_search; default value: false;The cost of the parameter can be calculated on the Pricing page", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behavioroptional fielddefines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "use_reasoning": { "type": "boolean", "description": "enable reasoning for the AI modeloptional fieldwhen enabled, the model will perform reasoning before generating a responserefer to the Models endpoint for a list of models that support reasoningdefault value: falseNote: if set to true, the minimum value for max_output_tokens is 1024Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true }, "postback_url": { "type": "string", "description": "URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special character in postback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "pingback_url": { "type": "string", "description": "notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special character in pingback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "model_name": "gemini-2.5-flash", "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "LlmMessageChainItem": { "type": "object", "properties": { "role": { "type": "string", "description": "role of the user from whom the message originates", "nullable": true }, "message": { "type": "string", "description": "message text", "nullable": true } } }, "AiOptimizationLlmMentionsAvailableFiltersResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsAvailableFiltersTaskInfo" } ], "nullable": true }, "nullable": true } } } ] }, "AiOptimizationLlmMentionsAvailableFiltersTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsAvailableFiltersResultInfo" } ], "nullable": true }, "nullable": true } } } ] }, "AiOptimizationLlmMentionsAvailableFiltersResultInfo": { "type": "object", "properties": { "search": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true } } }, "AiOptimizationGeminiLlmScraperTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraykeyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found", "nullable": true } } }, "HtmlItemInfo": { "type": "object", "properties": { "page": { "type": "integer", "description": "serial number of the returned HTML page", "nullable": true }, "date": { "type": "string", "description": "date and time when the HTML page was scanned\nin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201d\nexample:\n2019-11-15 12:57:46 +00:00", "nullable": true }, "html": { "type": "string", "description": "HTML\u00a0page", "nullable": true } } }, "AiOptimizationChatGptLlmScraperTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "model": { "type": "string", "description": "indicates the model version", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine resultsyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true }, "search_results": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ChatgptSearchResult" } ], "nullable": true }, "description": "array of search resultsall web search outputs the model retrieved when looking up information, including duplicates and unused entries", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SourceInfo" } ], "nullable": true }, "description": "array of sourcesthe sources the model actually cited or relied on in its final answer", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true }, "brand_entities": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ChatGptBrandEntity" } ], "nullable": true }, "description": "array of brand entitiescontains information on brands mentioned in the response", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results", "format": "int64", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search resultscontains types of search results (items) found.possible item types:chat_gpt_text, chat_gpt_table, chat_gpt_navigation_list, chat_gpt_images, chat_gpt_local_businesses, chat_gpt_products", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseChatGptLlmScraperElementItem" } ], "nullable": true }, "description": "items present in the element", "nullable": true } } }, "ChatGptBrandEntity": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "title": { "type": "string", "description": "name of the brand", "nullable": true }, "category": { "type": "string", "description": "category of the brand", "nullable": true }, "markdown": { "type": "string", "description": "brand name in markdown formatcontains brand name formatted in the markdown markup language", "nullable": true }, "urls": { "type": "object", "description": "array of URLs and domains relevant to the brand", "nullable": true } } }, "BaseChatGptLlmScraperElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "description": "group rank in SERPposition within a group of elements with identical type valuespositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERPabsolute position among all the elements", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "chat_gpt_text": "#/components/schemas/ChatGptTextElementItem", "chat_gpt_table": "#/components/schemas/ChatGptTableElementItem", "chat_gpt_navigation_list": "#/components/schemas/ChatGptNavigationListElementItem", "chat_gpt_images": "#/components/schemas/ChatGptImagesElementItem", "chat_gpt_products": "#/components/schemas/ChatGptProductsElementItem", "chat_gpt_local_businesses": "#/components/schemas/ChatGptLocalBusinessesElementItem" } } }, "SourceInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "title": { "type": "string", "description": "source title", "nullable": true }, "snippet": { "type": "string", "description": "source description", "nullable": true }, "domain": { "type": "string", "description": "source domain in SERP", "nullable": true }, "url": { "type": "string", "description": "source URL", "nullable": true }, "thumbnail": { "type": "string", "description": "source thumbnail", "nullable": true }, "source_name": { "type": "string", "description": "source name", "nullable": true }, "publication_date": { "type": "string", "description": "date and time when the result was publishedin the format: \u201cyear-month-date:minutes:UTC_difference_hours:UTC_difference_minutes\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true } } }, "ChatgptSearchResult": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "url": { "type": "string", "description": "result URL", "nullable": true }, "domain": { "type": "string", "description": "result domain", "nullable": true }, "title": { "type": "string", "description": "result title", "nullable": true }, "description": { "type": "string", "description": "result description", "nullable": true }, "breadcrumb": { "type": "string", "description": "breadcrumb", "nullable": true } } }, "AiOptimizationChatGptLlmScraperTaskGetHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTaskGetHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTaskGetHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTaskGetHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTaskGetHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraykeyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found", "nullable": true } } }, "AiOptimizationGeminiLlmResponsesTaskGetResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesTaskGetTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesTaskGetTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesTaskGetResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesTaskGetResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "description": "number of reasoning tokenstotal count of tokens used to generate reasoning content", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was used", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "AiOptimizationChatGptLlmScraperTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed taskunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "se_type": { "type": "string", "description": "type of search engineexample: llm_scraper", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_regular": { "type": "string", "description": "URL for collecting the results of the Regular taskif the Regular function is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the Advanced taskif the Advanced function is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the HTML taskif the HTML function is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "AiOptimizationGeminiLlmScraperLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 2000 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locationsexample:United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locationsexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code;if you use this field, you don't need to specify language_code;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languagesexample: English", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_name;if you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languagesexample: enn", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "AiOptimizationGeminiLlmResponsesTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesTaskGetResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesTaskGetTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesTaskGetTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesTaskGetResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesTaskGetResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "description": "number of reasoning tokenstotal count of tokens used to generate reasoning content", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was used", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "AiOptimizationClaudeLlmResponsesTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed taskunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "LLM model specified when setting the task", "nullable": true }, "se_type": { "type": "string", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint": { "type": "string", "description": "URL for collecting the results of the task", "nullable": true } } }, "AiOptimizationGeminiLlmScraperTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesLiveResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "description": "number of reasoning tokenstotal count of tokens used to generate reasoning content", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was used", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "AiOptimizationGeminiLlmScraperTaskGetAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTaskGetAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTaskGetAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTaskGetAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTaskGetAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "model": { "type": "string", "description": "indicates the model version", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SourceInfo" } ], "nullable": true }, "description": "array of sourcesthe sources the model actually cited or relied on in its final answer", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results", "format": "int64", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search resultscontains types of search results (items) found in SERP.possible item types:gemini_text, gemini_table, gemini_images", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseGeminiLlmScraperElementItem" } ], "nullable": true }, "description": "items present in the element", "nullable": true } } }, "BaseGeminiLlmScraperElementItem": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "rank_group": { "type": "integer", "description": "group rank in SERPposition within a group of elements with identical type valuespositions of elements with different type values are omitted from rank_group", "nullable": true }, "rank_absolute": { "type": "integer", "description": "absolute rank in SERPabsolute position among all the elements in SERP", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true } }, "additionalProperties": false, "discriminator": { "propertyName": "type", "mapping": { "gemini_text": "#/components/schemas/GeminiTextElementItem", "gemini_table": "#/components/schemas/GeminiTableElementItem", "gemini_images": "#/components/schemas/GeminiImagesElementItem" } } }, "AiOptimizationLlmMentionsTopDomainsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsTopDomainsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationLlmMentionsTopDomainsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsTopDomainsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationLlmMentionsTopDomainsLiveResultInfo": { "type": "object", "properties": { "total": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationResultTotalInfo" } ], "description": "aggregated mentions metrics summarycontains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionssLiveItem" } ], "nullable": true }, "description": "individual domain resultsarray containing detailed mention metrics for each of the found top domains", "nullable": true } } }, "AiOptimizationResultTotalInfo": { "type": "object", "properties": { "location": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "location-based groupingarray of objects containing mention metrics segmented by geographical location", "nullable": true }, "language": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "language-based groupingarray of objects containing mention metrics segmented by content language", "nullable": true }, "platform": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "platform-based groupingarray of group elements containing mention metrics segmented by AI platform", "nullable": true }, "sources_domain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "found source domains relevant to the targetarray of objects containing data on top domains that are cited as sources in LLM responses", "nullable": true }, "search_results_domain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "found search results domains relevant to the targetarray of objects containing data on top domains that appear in search results related to LLM queries", "nullable": true }, "brand_entities_title": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "data on brand entities relevant to the targetarray of objects containing data on brand entity titles that appear in search results related to LLM queries", "nullable": true }, "brand_entities_category": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "data on brand entities relevant to the targetarray of objects containing data on brand entity categories that appear in search results related to LLM queries", "nullable": true } } }, "GroupElement": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "key": { "type": "string", "description": "grouping identifierthe specific identifier for the grouping dimension", "nullable": true }, "mentions": { "type": "integer", "description": "total LLM mentions countthe number of times the target keyword or domain were mentioned in relation to this specific grouping key", "nullable": true }, "ai_search_volume": { "type": "integer", "description": "current AI search volume rate of a keywordlearn more about this metric here", "format": "int64", "nullable": true }, "impressions": { "type": "integer", "description": "current AI impressions rate of a keyword", "format": "int64", "nullable": true } } }, "AiOptimizationLlmMentionssLiveItem": { "type": "object", "properties": { "key": { "type": "string", "description": "URL of a found pagethe URL of a page found in LLM mentions for the specified target", "nullable": true }, "location": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "location-based groupingarray of objects containing page mention metrics segmented by geographical location", "nullable": true }, "language": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "language-based groupingarray of objects containing page mention metrics segmented by content language", "nullable": true }, "platform": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "platform-based groupingarray of group elements containing page mention metrics segmented by AI platform", "nullable": true }, "sources_domain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "source domains relevant to the specific pagearray of objects containing data on domains that are cited as sources in LLM responses", "nullable": true }, "search_results_domain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "search results domains relevant to the specific pagearray of objects containing data on domains that appear in search results related to LLM queries", "nullable": true }, "brand_entities_title": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "data on brand entities relevant to the targetarray of objects containing data on brand entity titles that appear in search results related to LLM queries", "nullable": true }, "brand_entities_category": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GroupElement" } ], "nullable": true }, "description": "data on brand entities relevant to the targetarray of objects containing data on brand entity categories that appear in search results related to LLM queries", "nullable": true } } }, "AiOptimizationChatGptLlmResponsesTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesModelsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesModelsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesModelsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesModelsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesModelsResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model", "nullable": true }, "web_search_supported": { "type": "boolean", "description": "web search support for the AI modelif true, the web_search parameter can be set with the AI model", "nullable": true }, "task_post_supported": { "type": "boolean", "description": "indicates if Standard (POST-GET) data retrieval is supportedif true, you can use the Standard (POST-GET) data retrieval method with the AI model", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLocationsCountryResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLocationsCountryTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLocationsCountryTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLocationsCountryResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLocationsCountryResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate locationexample:\"location_code\": 9041134,\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\"location_code_parent\": 20044where location_code_parent corresponds to:\"location_code\": 20044,\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } }, "AiOptimizationGeminiLlmResponsesModelsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesModelsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesModelsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesModelsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesModelsResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model", "nullable": true }, "web_search_supported": { "type": "boolean", "description": "web search support for the AI modelif true, the web_search parameter can be set with the AI model", "nullable": true }, "task_post_supported": { "type": "boolean", "description": "indicates if Standard (POST-GET) data retrieval is supportedif true, you can use the Standard (POST-GET) data retrieval method with the AI model", "nullable": true } } }, "AiOptimizationChatGptLlmResponsesLiveRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;minimum value for non-reasoning models: 16;maximum value: 4096;default value: 2048Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse; lower values make output more focused;minimum value: 0maximum value: 2default value: 0.94Note: not supported in reasoning models", "nullable": true }, "top_p": { "type": "number", "description": "", "nullable": true }, "web_search": { "type": "boolean", "description": "enable web searchoptional fieldwhen enabled, the AI model can access and cite current web information;default value: false;Note: refer to the Models endpoint for a list of models that support web_search;", "nullable": true }, "force_web_search": { "type": "boolean", "description": "force AI agent to use web searchoptional fieldto enable this parameter, web_search must also be enabled;when enabled, the AI model is forced to access and cite current web information;default value: false;Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response Note #2: not supported in reasoning models", "nullable": true }, "web_search_country_iso_code": { "type": "string", "description": "ISO country code of the locationoptional fieldrequired if web_search_city is specified;to enable this parameter, web_search must also be enabled;when enabled, the AI model will search the web from the country you specify;Note: not supported in o3-mini, o1-pro, o1 models", "nullable": true }, "web_search_city": { "type": "string", "description": "city name of the locationoptional fieldNote: specify web_search_country_iso_code to use this parameterNote #2: not supported in o3-mini, o1-pro, o1 models", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behaviouroptional fielddefines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "max_output_tokens": 200, "temperature": 0.3, "top_p": 0.5, "model_name": "gpt-4.1-mini", "web_search": true, "web_search_country_iso_code": "FR", "web_search_city": "Paris", "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "AiOptimizationClaudeLlmResponsesModelsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesModelsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesModelsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesModelsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesModelsResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model", "nullable": true }, "web_search_supported": { "type": "boolean", "description": "web search support for the AI modelif true, the web_search parameter can be set with the AI model", "nullable": true }, "task_post_supported": { "type": "boolean", "description": "indicates if Standard (POST-GET) data retrieval is supportedif true, you can use the Standard (POST-GET) data retrieval method with the AI model", "nullable": true } } }, "AiOptimizationChatGptLlmResponsesTaskPostRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;for example, if gpt-4.1 is specified, the gpt-4.1-2025-04-14 will be set as model_name automatically;you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value for reasoning models (e.g., reasoning is true in the Models endpoint): 1024;minimum value for non-reasoning models: 16;maximum value: 4096;default value: 2048", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse; lower values make output more focused;minimum value: 0maximum value: 2default value: 0.94Note: not supported in reasoning models", "nullable": true }, "top_p": { "type": "number", "description": "", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behaviouroptional fielddefines the AI's role, tone, or specific behavior;you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "postback_url": { "type": "string", "description": "URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special character in postback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "pingback_url": { "type": "string", "description": "notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special character in pingback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data array of the response", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "model_name": "gpt-4.1-mini", "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "AiOptimizationAiKeywordDataAvailableFiltersResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataAvailableFiltersTaskInfo" } ], "nullable": true }, "nullable": true } } } ] }, "AiOptimizationAiKeywordDataAvailableFiltersTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataAvailableFiltersResultInfo" } ], "nullable": true }, "nullable": true } } } ] }, "AiOptimizationAiKeywordDataAvailableFiltersResultInfo": { "type": "object", "properties": { "popular_questions": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "nullable": true } } }, "AiOptimizationLlmMentionsAggregatedMetricsLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLLmMentionsTargetElement" } ], "nullable": true }, "description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity", "nullable": true }, "domain_entity": { "type": "object", "description": "domain entity in the target arrayexample:{\"domain\": \"en.wikipedia.org\", \"search_filter\": \"exclude\", \"search_scope\": [\"sources\"]}", "nullable": true }, "domain": { "type": "string", "description": "target domainrequired field if you don't specify keywordyou can specify up to 63 characters in the domain field;a domain should be specified without https:// and www.", "nullable": true }, "search_filter": { "type": "string", "description": "target keyword search filteroptional fieldpossible values:include, excludedefault value: include", "nullable": true }, "search_scope": { "type": "array", "items": { "type": "string" }, "description": "target keyword search scopeoptional fieldpossible values:any, question, answer, brand_entities, fan_out_queriesdefault value: any", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains of the target domain will be included in the searchoptional fieldif set to true, the subdomains will be included in the searchdefault value: false", "nullable": true }, "keyword_entity": { "type": "object", "description": "keyword entity in the target arrayexample:{\"keyword\": \"bmw\", \"search_filter\": \"include\", \"search_scope\": [\"question\"], \"match_type \": \"partial_match\"}", "nullable": true }, "keyword": { "type": "string", "description": "target keywordrequired field if you don't specify domainyou can specify up to 250 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article", "nullable": true }, "match_type": { "type": "string", "description": "target keyword match typeoptional fieldword_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for \u201clight\u201d will return results with \u201clight bulb\u201d, \u201clight switch\u201d);partial_match - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for \u201clight\u201d will return results with \u201clighting\u201d, \u201chighlight\u201d);possible values:word_match, partial_matchdefault value: word_match", "nullable": true }, "location_name": { "type": "string", "description": "full name of search locationoptional fieldif you use this field, you don't need to specify location_codeif you don't specify this field, the location_code with 2840 value will be used by default;you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for United States only", "nullable": true }, "location_code": { "type": "integer", "description": "search location codeoptional fieldif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: 2840Note: chat_gpt data is available for 2840 only", "nullable": true }, "language_name": { "type": "string", "description": "full name of search languageoptional fieldif you use this field, you don't need to specify language_code;if you don't specify this field, the language_code with en value will be used by default;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for English only", "nullable": true }, "language_code": { "type": "string", "description": "search language codeoptional fieldif you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: enNote: chat_gpt data is available for en onlyn", "nullable": true }, "platform": { "type": "string", "description": "target platformoptional fieldpossible values:chat_gpt, googledefault value: googleNote: the data returned depends on the selected platformNote #2:chat_gpt data is available for the United States and English only", "nullable": true }, "initial_dataset_filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of filter expressions applied before aggregationoptional fieldyou can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_matchyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"ai_search_volume\",\">\",\"1000\"]The full list of possible filters is available here.", "nullable": true }, "internal_list_limit": { "type": "integer", "description": "maximum number of elements within internal arraysoptional fieldyou can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domainminimum value: 1maximum value: 20default value: 10", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "es", "location_code": 2840, "platform": "google", "target": [ { "domain": "en.wikipedia.org", "search_filter": "exclude" }, { "keyword": "bmw", "search_scope": [ "answer" ] } ], "initial_dataset_filters": [ [ "ai_search_volume", ">", 10 ] ], "internal_list_limit": 10 } ] }, "BaseAiOptimizationLLmMentionsTargetElement": { "type": "object", "properties": { "search_scope": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "target domain search scope\noptional field\npossible values:\nany, sources, search_results\ndefault value: any", "nullable": true }, "search_filter": { "type": "string", "description": "target domain search filter\noptional field\npossible values:\ninclude, exclude\ndefault value: include", "nullable": true } }, "discriminator": { "propertyName": "type", "mapping": { "domain": "#/components/schemas/AiOptimizationLLmMentionsDomainElement", "keyword": "#/components/schemas/AiOptimizationLLmMentionsKeywordElement" } } }, "AiOptimizationGeminiLlmScraperLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLanguagesResultInfo": { "type": "object", "properties": { "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLiveAdvancedRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 2000 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locationsexample:United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locationsexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code;if you use this field, you don't need to specify language_code;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_name;if you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages", "nullable": true }, "force_web_search": { "type": "boolean", "description": "force AI agent to use web searchoptional fieldwhen enabled, the AI model is forced to access and cite current web information;default value: false;Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "AiOptimizationGeminiLlmResponsesTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmResponsesTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmResponsesTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed taskunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "LLM model specified when setting the task", "nullable": true }, "se_type": { "type": "string", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint": { "type": "string", "description": "URL for collecting the results of the task", "nullable": true } } }, "AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "items_count": { "type": "integer", "description": "number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveItem" } ], "nullable": true }, "description": "contains specified keywords with their AI search volume rates", "nullable": true } } }, "AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveItem": { "type": "object", "properties": { "keyword": { "type": "string", "description": "specified keyword", "nullable": true }, "ai_search_volume": { "type": "integer", "description": "current AI search volume rate of a keywordlearn more about this metric here", "format": "int64", "nullable": true }, "ai_monthly_searches": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiMonthlySearches" } ], "nullable": true }, "description": "monthly AI search volume ratesarray of objects with AI search volume rates in a certain month of a year", "nullable": true } } }, "AiMonthlySearches": { "type": "object", "properties": { "year": { "type": "integer", "description": "year", "nullable": true }, "month": { "type": "integer", "description": "month", "nullable": true }, "ai_search_volume": { "type": "integer", "description": "AI search volume rate in a certain month of a yearlearn more about this metric here", "format": "int64", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLiveHtmlRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 2000 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/locationsexample:United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locationsexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_codeif you use this field, you don't need to specify language_codeyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languagesexample:English", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_nameif you use this field, you don't need to specify language_nameyou can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languagesexample:enn", "nullable": true }, "force_web_search": { "type": "boolean", "description": "force AI agent to use web searchoptional fieldwhen enabled, the AI model is forced to access and cite current web information;default value: false;Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response", "nullable": true }, "expand_citations": { "type": "boolean", "description": "return expanded citation bar in HTML resultsoptional fieldto enable this parameter, force_web_search must also be enabled;when enabled, the endpoint will return HTML data from the expanded citation bar;default value: false", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "AiOptimizationGeminiLlmScraperLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "string", "description": "the code of the superordinate locationexample:\"location_code\": 9041134,\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\"location_code_parent\": 20044where location_code_parent corresponds to:\"location_code\": 20044,\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } }, "AiOptimizationAiKeywordDataLocationsAndLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataLocationsAndLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationAiKeywordDataLocationsAndLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationAiKeywordDataLocationsAndLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationAiKeywordDataLocationsAndLanguagesResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "available_languages": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AvailableLanguages" } ], "nullable": true }, "description": "supported languages\ncontains the languages which are supported for a specific location", "nullable": true } } }, "AvailableLanguages": { "type": "object", "properties": { "available_sources": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "supported sources\ncontains the sources of data supported for a specific location and language combination\nonly google and bing are currently available", "nullable": true }, "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true }, "keywords": { "type": "integer", "description": "the number of keywords available for the given location and language", "nullable": true }, "serps": { "type": "integer", "description": "the number of SERP pages available for the given location and language", "nullable": true } } }, "AiOptimizationGeminiLlmResponsesLiveRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;for example, if gemini-1.5-pro is specified, the gemini-1.5-pro-002 will be set as model_name automatically;you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value: 1maximum value: 4096;default value: 2048;Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limitNote #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1024", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse lower values make output more focusedminimum value: 0maximum value: 2default value: 1.3", "nullable": true }, "top_p": { "type": "number", "description": "diversity of the AI responseoptional field controls diversity of the response by limiting token selectionminimum value: 0maximum value: 1 default value: 0.9", "nullable": true }, "web_search": { "type": "boolean", "description": "enable web search for current informationoptional fieldwhen enabled, the AI model can access and cite current web information;Note: refer to the Models endpoint for a list of models that support web_search; default value: false;The cost of the parameter can be calculated on the Pricing page", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behavioroptional fielddefines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "use_reasoning": { "type": "boolean", "description": "enable reasoning for the AI modeloptional fieldwhen enabled, the model will perform reasoning before generating a responserefer to the Models endpoint for a list of models that support reasoningdefault value: falseNote: if set to true, the minimum value for max_output_tokens is 1024Note #2: for Gemini Pro models, the use_reasoning will automatically be set to true", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "max_output_tokens": 200, "temperature": 0.3, "top_p": 0.5, "model_name": "gemini-2.5-flash", "web_search": true, "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "AiOptimizationLlmMentionsSearchLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLLmMentionsTargetElement" } ], "nullable": true }, "description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity", "nullable": true }, "domain_entity": { "type": "object", "description": "domain entity in the target arrayexample:{\"domain\": \"en.wikipedia.org\", \"search_filter\": \"exclude\", \"search_scope\": [\"sources\"]}", "nullable": true }, "domain": { "type": "string", "description": "target domainrequired field if you don't specify keywordyou can specify up to 63 characters in the domain field;a domain should be specified without https:// and www.", "nullable": true }, "search_filter": { "type": "string", "description": "target keyword search filteroptional fieldpossible values:include, excludedefault value: include", "nullable": true }, "search_scope": { "type": "array", "items": { "type": "string" }, "description": "target keyword search scopeoptional fieldpossible values:any, question, answer, brand_entities, fan_out_queriesdefault value: any", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains of the target domain will be included in the searchoptional fieldif set to true, the subdomains will be included in the searchdefault value: false", "nullable": true }, "keyword_entity": { "type": "object", "description": "keyword entity in the target arrayexample:{\"keyword\": \"bmw\", \"search_filter\": \"include\", \"search_scope\": [\"question\"], \"match_type \": \"partial_match\"}", "nullable": true }, "keyword": { "type": "string", "description": "target keywordrequired field if you don't specify domainyou can specify up to 250 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article", "nullable": true }, "match_type": { "type": "string", "description": "target keyword match typedefines how the specified keyword is matchedoptional fieldpossible values:word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for \"light\" will return results with \"light bulb\", \"light switch\");partial_match - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for \"light\" will return results with \"lighting\", \"highlight\");default value: word_match", "nullable": true }, "location_name": { "type": "string", "description": "full name of search locationoptional fieldif you use this field, you don't need to specify location_codeif you don't specify this field, the location_code with 2840 value will be used by default;you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for United States only", "nullable": true }, "location_code": { "type": "integer", "description": "search location codeoptional fieldif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: 2840Note: chat_gpt data is available for 2840 only", "nullable": true }, "language_name": { "type": "string", "description": "full name of search languageoptional fieldif you use this field, you don't need to specify language_code;if you don't specify this field, the language_code with en value will be used by default;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for English only", "nullable": true }, "language_code": { "type": "string", "description": "search language codeoptional fieldif you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: enNote: chat_gpt data is available for en onlyn", "nullable": true }, "platform": { "type": "string", "description": "target platformoptional fieldpossible values:chat_gpt, googledefault value: googleNote: the data returned depends on the selected platformNote #2:chat_gpt data is available for the United States and English only", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of results filtering parametersoptional fieldyou can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_matchyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"ai_search_volume\",\">\",\"1000\"]The full list of possible filters is available here.", "nullable": true }, "order_by": { "type": "array", "items": { "type": "string" }, "description": "results sorting rulesoptional fieldyou can use the same values as in the filters array to sort the resultspossible sorting types:asc - results will be sorted in the ascending orderdesc - results will be sorted in the descending orderyou should use a comma to set up a sorting typeexample:[\"ai_search_volume,desc\"]note that you can set no more than three sorting rules in a single requestyou should use a comma to separate several sorting rules", "nullable": true }, "offset": { "type": "integer", "description": "offset in the results array of the returned mentions dataoptional fielddefault value: 0example: if you specify the 10 value, the first ten mentions objects in the results array will be omitted and the data will be provided for the successive objects;Note: the maximum value is 9,000, use the search_after_token if you would like to offset more results", "nullable": true }, "search_after_token": { "type": "string", "description": "token for subsequent requestsoptional fieldprovided in the identical filed of the response to each request;use this parameter to avoid timeouts while trying to obtain over 20,000 results in a single request;by specifying the unique search_after_token value from the response array, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task ;Note: if the search_after_token is specified in the request, all other parameters should be identical to the previous request", "nullable": true }, "limit": { "type": "integer", "description": "the maximum number of returned objectsoptional fielddefault value: 100maximum value: 1000", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_name": "English", "location_code": 2840, "target": [ { "domain": "dataforseo.com", "search_filter": "exclude" }, { "keyword": "bmw", "search_scope": [ "answer" ] } ], "platform": "google", "filters": [ [ "ai_search_volume", ">", 1000 ] ], "order_by": [ "ai_search_volume,desc" ], "offset": 0, "limit": 3 } ] }, "AiOptimizationPerplexityLlmResponsesModelsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationPerplexityLlmResponsesModelsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationPerplexityLlmResponsesModelsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationPerplexityLlmResponsesModelsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationPerplexityLlmResponsesModelsResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model", "nullable": true }, "web_search_supported": { "type": "boolean", "description": "web search support for the AI modelif true, the web_search parameter can be set with the AI model", "nullable": true }, "task_post_supported": { "type": "boolean", "description": "indicates if Standard (POST-GET) data retrieval is supportedif true, you can use the Standard (POST-GET) data retrieval method with the AI model", "nullable": true } } }, "AiOptimizationLlmMentionsCrossAggregatedMetricsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsCrossAggregatedMetricsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationLlmMentionsCrossAggregatedMetricsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsCrossAggregatedMetricsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationLlmMentionsCrossAggregatedMetricsLiveResultInfo": { "type": "object", "properties": { "total": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationResultTotalInfo" } ], "description": "aggregated mentions metrics summarycontains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionssLiveItem" } ], "nullable": true }, "description": "contains relevant mentions data", "nullable": true } } }, "AiOptimizationAiKeywordDataKeywordsSearchVolumeLiveRequestInfo": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "description": "keywordsrequired fieldUTF-8 encodingThe maximum number of keywords you can specify: 1000;The maximum number of characters in a single keyword: 250;The keywords will be converted to lowercase format;learn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of the locationrequired field if you don't specify location_codeNote: it is required to specify either location_name or location_codeyou can receive the list of available locations with their location_name by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languagesexample:United Kingdom", "nullable": true }, "location_code": { "type": "integer", "description": "unique location identifierrequired field if you don't specify location_nameNote: it is required to specify either location_name or location_codeyou can receive the list of available locations with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languagesexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of the languagerequired field if you don't specify language_codeif you use this field, you don't need to specify language_codeyou can receive the list of available languages with their language_name by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languagesexample:English", "nullable": true }, "language_code": { "type": "string", "description": "language coderequired field if you don't specify language_nameif you use this field, you don't need to specify language_nameyou can receive the list of available languages with their language_code by making a separate request to thehttps://api.dataforseo.com/v3/ai_optimization/ai_keyword_data/locations_and_languagesexample:en", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_name": "English", "location_code": 2840, "keywords": [ "iphone", "seo" ] } ] }, "AiOptimizationLlmMentionsSearchLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsSearchLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationLlmMentionsSearchLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsSearchLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationLlmMentionsSearchLiveResultInfo": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "total amount of results relevant the request", "format": "int64", "nullable": true }, "current_offset": { "type": "integer", "description": "the number of mentions objects that are omitted in the items array", "nullable": true }, "search_after_token": { "type": "string", "description": "token for subsequent requestsby specifying the unique search_after_token when setting a new task, you will get the subsequent results of the initial task;search_after_token values are unique for each subsequent task", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsSearchLiveItem" } ], "nullable": true }, "description": "contains relevant mentions data", "nullable": true } } }, "AiOptimizationLlmMentionsSearchLiveItem": { "type": "object", "properties": { "platform": { "type": "string", "description": "platform received in a POST array", "nullable": true }, "model_name": { "type": "string", "description": "name of the AI model from which the data was retrievedNote: for the google platform type, the value is always google_ai_overview", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "question": { "type": "string", "description": "relevant question", "nullable": true }, "answer": { "type": "string", "description": "relevant answer in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/Sources" } ], "nullable": true }, "description": "array of sourcesthe sources the model cited or relied on in its final answer", "nullable": true }, "search_results": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SearchResults" } ], "nullable": true }, "description": "array of search resultsall web search outputs the model retrieved when looking up information, including duplicates and unused entries", "nullable": true }, "ai_search_volume": { "type": "integer", "description": "current AI search volume rate of a keywordlearn more about this metric here", "format": "int64", "nullable": true }, "monthly_searches": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/MonthlySearchesInfo" } ], "nullable": true }, "description": "monthly AI search volume ratesarray of objects with AI search volume rates in a certain month of a year", "nullable": true }, "first_response_at": { "type": "string", "description": "date and time when the response data was first recordedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2025-10-21 06:25:30 +00:00", "nullable": true }, "last_response_at": { "type": "string", "description": "date and time when the response data was last updatedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2025-10-21 06:25:30 +00:00", "nullable": true }, "brand_entities": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BrandEntities" } ], "nullable": true }, "description": "array of brand entitiescontains information on brands mentioned in the response", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "SearchResults": { "type": "object", "properties": { "description": { "type": "string", "description": "result description", "nullable": true }, "breadcrumb": { "type": "string", "description": "breadcrumb", "nullable": true }, "position": { "type": "integer", "description": "position in the results", "nullable": true }, "title": { "type": "string", "description": "result title", "nullable": true }, "domain": { "type": "string", "description": "result domain", "nullable": true }, "url": { "type": "string", "description": "result URL", "nullable": true }, "publication_date": { "type": "string", "description": "date and time when the result was publishedin the format: \u201cyear-month-date:minutes:UTC_difference_hours:UTC_difference_minutes\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true } } }, "MonthlySearchesInfo": { "type": "object", "properties": { "year": { "type": "integer", "description": "year", "nullable": true }, "month": { "type": "integer", "description": "month", "nullable": true }, "search_volume": { "type": "integer", "description": "monthly average search volume rate", "nullable": true } } }, "Sources": { "type": "object", "properties": { "snippet": { "type": "string", "description": "source description", "nullable": true }, "source_name": { "type": "string", "description": "source name", "nullable": true }, "thumbnail": { "type": "string", "description": "source thumbnail", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true }, "position": { "type": "integer", "description": "position in the results", "nullable": true }, "title": { "type": "string", "description": "source title", "nullable": true }, "domain": { "type": "string", "description": "source domain", "nullable": true }, "url": { "type": "string", "description": "source URL", "nullable": true }, "publication_date": { "type": "string", "description": "date and time when the result was publishedin the format: \u201cyear-month-date:minutes:UTC_difference_hours:UTC_difference_minutes\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true } } }, "BrandEntities": { "type": "object", "properties": { "position": { "type": "integer", "description": "position in the results", "nullable": true }, "title": { "type": "string", "description": "name of the brand", "nullable": true }, "category": { "type": "string", "description": "category of the brand", "nullable": true } } }, "AiOptimizationLlmMentionsTopPagesLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLLmMentionsTargetElement" } ], "nullable": true }, "description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity", "nullable": true }, "domain_entity": { "type": "object", "description": "domain entity in the target arrayexample:{\"domain\": \"en.wikipedia.org\", \"search_filter\": \"exclude\", \"search_scope\": [\"sources\"]}", "nullable": true }, "domain": { "type": "string", "description": "target domainrequired field if you don't specify keywordyou can specify up to 63 characters in the domain field;a domain should be specified without https:// and www.", "nullable": true }, "search_filter": { "type": "string", "description": "target keyword search filteroptional fieldpossible values:include, excludedefault value: include", "nullable": true }, "search_scope": { "type": "array", "items": { "type": "string" }, "description": "target keyword search scopeoptional fieldpossible values:any, question, answer, brand_entities, fan_out_queriesdefault value: any", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains of the target domain will be included in the searchoptional fieldif set to true, the subdomains will be included in the searchdefault value: false", "nullable": true }, "keyword_entity": { "type": "object", "description": "keyword entity in the target arrayexample:{\"keyword\": \"bmw\", \"search_filter\": \"include\", \"search_scope\": [\"question\"], \"match_type \": \"partial_match\"}", "nullable": true }, "keyword": { "type": "string", "description": "target keywordrequired field if you don't specify domainyou can specify up to 250 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article", "nullable": true }, "match_type": { "type": "string", "description": "target keyword match typeoptional fieldpossible values:word_match, partial_matchword_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the seed key phrase.partial_match - searches for any occurrence of the keyword or its parts within the contentdefault value: word_match", "nullable": true }, "location_name": { "type": "string", "description": "full name of search locationoptional fieldif you use this field, you don't need to specify location_codeif you don't specify this field, the location_code with 2840 value will be used by default;you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for United States only", "nullable": true }, "location_code": { "type": "integer", "description": "search location codeoptional fieldif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: 2840Note: chat_gpt data is available for 2840 only", "nullable": true }, "language_name": { "type": "string", "description": "full name of search languageoptional fieldif you use this field, you don't need to specify language_code;if you don't specify this field, the language_code with en value will be used by default;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for English only", "nullable": true }, "language_code": { "type": "string", "description": "search language codeoptional fieldif you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: enNote: chat_gpt data is available for en onlyn", "nullable": true }, "platform": { "type": "string", "description": "target platformoptional fieldpossible values:chat_gpt, googledefault value: googleNote: the data returned depends on the selected platformNote #2:chat_gpt data is available for the United States and English only", "nullable": true }, "links_scope": { "type": "string", "description": "links source scopeoptional fieldthis parameter specifies which links will be used to extract pages and aggregation datapossible values: sources, search_resultsdefault value: sources", "nullable": true }, "initial_dataset_filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of filter expressions applied before aggregationoptional fieldyou can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_matchyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"ai_search_volume\",\">\",\"1000\"]The full list of possible filters is available here.", "nullable": true }, "items_list_limit": { "type": "integer", "description": "maximum number of results in the items arrayoptional fieldyou can use this parameter to limit the number of data objects you receive in the items arrayminimum value: 1maximum value: 10default value: 5", "nullable": true }, "internal_list_limit": { "type": "integer", "description": "maximum number of elements within internal arraysoptional fieldyou can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domainminimum value: 1maximum value: 10default value: 5", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "platform": "google", "target": [ { "keyword": "bmw", "search_scope": [ "answer" ] }, { "keyword": "auto", "search_scope": [ "question" ], "match_type": "partial_match" } ], "links_scope": "sources", "initial_dataset_filters": [ [ "ai_search_volume", ">", 10 ] ], "items_list_limit": 3, "internal_list_limit": 2 } ] }, "AiOptimizationChatGptLlmResponsesTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed taskunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "LLM model specified when setting the task", "nullable": true }, "se_type": { "type": "string", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint": { "type": "string", "description": "URL for collecting the results of the task", "nullable": true } } }, "AiOptimizationClaudeLlmResponsesTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "AiOptimizationLlmMentionsLocationsAndLanguagesResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsLocationsAndLanguagesTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationLlmMentionsLocationsAndLanguagesTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsLocationsAndLanguagesResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationLlmMentionsLocationsAndLanguagesResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "available_languages": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ResultAvailableLanguages" } ], "nullable": true }, "description": "supported languagescontains the languages which are supported for a specific location", "nullable": true } } }, "ResultAvailableLanguages": { "type": "object", "properties": { "available_platforms": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "supported LLM platformscontains the sources of data supported for a specific location and language combinationonly google and chat_gpt are currently available", "nullable": true }, "language_name": { "type": "string", "description": "language name", "nullable": true }, "language_code": { "type": "string", "description": "language code according to ISO 639-1", "nullable": true }, "responses_count": { "type": "integer", "description": "number of LLM responsesthe number of LLM responses available in the database for the certain location and language parameters", "format": "int64", "nullable": true } } }, "AiOptimizationGeminiLlmScraperLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraykeyword is returned with decoded %## (plus character '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLiveHtmlResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLiveHtmlTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLiveHtmlTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLiveHtmlResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLiveHtmlResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraykeyword is returned with decoded %## (plus character '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/HtmlItemInfo" } ], "nullable": true }, "description": "elements of search results found", "nullable": true } } }, "AiOptimizationGeminiLlmScraperTasksReadyResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTasksReadyTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTasksReadyTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperTasksReadyResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperTasksReadyResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "task identifier of the completed taskunique task identifier in our system in the UUID format", "nullable": true }, "se": { "type": "string", "description": "search engine specified when setting the task", "nullable": true }, "function": { "type": "string", "description": "search engine functionexample: llm_scraper", "nullable": true }, "date_posted": { "type": "string", "description": "date when the task was posted (in the UTC format)", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifier", "nullable": true }, "endpoint_advanced": { "type": "string", "description": "URL for collecting the results of the Advanced taskif the Advanced function is not supported in the specified endpoint, the value will be null", "nullable": true }, "endpoint_html": { "type": "string", "description": "URL for collecting the results of the HTML taskif the HTML function is not supported in the specified endpoint, the value will be null", "nullable": true } } }, "AiOptimizationGeminiLlmScraperLiveHtmlRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 2000 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "location_name": { "type": "string", "description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locationsexample:United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locationsexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_codeif you use this field, you don't need to specify language_codeyou can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languagesexample:English", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_nameif you use this field, you don't need to specify language_nameyou can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languagesexample:enn", "nullable": true }, "expand_citations": { "type": "boolean", "description": "return expanded citation bar in HTML resultsoptional fieldwhen enabled, the endpoint will return HTML data from the expanded citation bar;default value: false", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "AiOptimizationGeminiLlmScraperTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 2000 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locationsexample:United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/locationsexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code;if you use this field, you don't need to specify language_code;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languagesexample:English", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_name;if you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/gemini/llm_scraper/languagesexample:enn", "nullable": true }, "expand_citations": { "type": "boolean", "description": "return expanded citation bar in HTML resultsoptional fieldwhen enabled, the HTML endpoint will return data from the expanded citation bar;default value: false", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true }, "postback_url": { "type": "string", "description": "URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special characters in postback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced, html", "nullable": true }, "pingback_url": { "type": "string", "description": "notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special characters in pingback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "albert einstein" } ] }, "AiOptimizationChatGptLlmResponsesTaskGetResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesTaskGetTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesTaskGetTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmResponsesTaskGetResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmResponsesTaskGetResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "description": "number of reasoning tokenstotal count of tokens used to generate reasoning content", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was used", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "AiOptimizationChatGptLlmScraperTaskPostRequestInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keywordrequired fieldyou can specify up to 2000 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article" }, "priority": { "type": "integer", "description": "task priorityoptional fieldcan take the following values:1 \u2013 normal execution priority (set by default)2 \u2013 high execution priorityYou will be additionally charged for the tasks with high execution priority.The cost can be calculated on the Pricing page.", "nullable": true }, "location_name": { "type": "string", "description": "full name of search engine locationrequired field if you don't specify location_codeif you use this field, you don't need to specify location_codeyou can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locationsexample:United States", "nullable": true }, "location_code": { "type": "integer", "description": "search engine location coderequired field if you don't specify location_nameif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engines with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/locationsexample:2840", "nullable": true }, "language_name": { "type": "string", "description": "full name of search engine languagerequired field if you don't specify language_code;if you use this field, you don't need to specify language_code;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languages", "nullable": true }, "language_code": { "type": "string", "description": "search engine language coderequired field if you don't specify language_name;if you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/chat_gpt/llm_scraper/languagesn", "nullable": true }, "force_web_search": { "type": "boolean", "description": "force AI agent to use web searchoptional fieldwhen enabled, the AI model is forced to access and cite current web information;default value: false;Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response", "nullable": true }, "expand_citations": { "type": "boolean", "description": "return expanded citation bar in HTML resultsoptional fieldto enable this parameter, force_web_search must also be enabled;when enabled, the HTML endpoint will return data from the expanded citation bar;default value: false", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true }, "postback_url": { "type": "string", "description": "URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special characters in postback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "postback_data": { "type": "string", "description": "postback_url datatyperequired field if you specify postback_urlcorresponds to the function you used for setting a taskpossible values:advanced, html", "nullable": true }, "pingback_url": { "type": "string", "description": "notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special characters in pingback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "keyword": "what is chatgpt" } ] }, "AiOptimizationLlmMentionsTopDomainsLiveRequestInfo": { "type": "object", "properties": { "target": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLLmMentionsTargetElement" } ], "nullable": true }, "description": "array of objects containing target entities\nrequired field\nyou can specify up to 10 entities (objects) in the target field\none target entity can contain either one domain or one keyword and related parameters\nexamples:\n\ntarget array with a domain entity", "nullable": true }, "domain_entity": { "type": "object", "description": "domain entity in the target arrayexample:{\"domain\": \"en.wikipedia.org\", \"search_filter\": \"exclude\", \"search_scope\": [\"sources\"]}", "nullable": true }, "domain": { "type": "string", "description": "target domainrequired field if you don't specify keywordyou can specify up to 63 characters in the domain field;a domain should be specified without https:// and www.", "nullable": true }, "search_filter": { "type": "string", "description": "target keyword search filteroptional fieldpossible values:include, excludedefault value: include", "nullable": true }, "search_scope": { "type": "array", "items": { "type": "string" }, "description": "target keyword search scopeoptional fieldpossible values:any, question, answer, brand_entities, fan_out_queriesdefault value: any", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains of the target domain will be included in the searchoptional fieldif set to true, the subdomains will be included in the searchdefault value: false", "nullable": true }, "keyword_entity": { "type": "object", "description": "keyword entity in the target arrayexample:{\"keyword\": \"bmw\", \"search_filter\": \"include\", \"search_scope\": [\"question\"], \"match_type \": \"partial_match\"}", "nullable": true }, "keyword": { "type": "string", "description": "target keywordrequired field if you don't specify domainyou can specify up to 250 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article", "nullable": true }, "match_type": { "type": "string", "description": "target keyword match typeoptional fieldpossible values:word_match, partial_matchword_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the seed key phrase.partial_match - searches for any occurrence of the keyword or its parts within the contentdefault value: word_match", "nullable": true }, "location_name": { "type": "string", "description": "full name of search locationoptional fieldif you use this field, you don't need to specify location_codeif you don't specify this field, the location_code with 2840 value will be used by default;you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for United States only", "nullable": true }, "location_code": { "type": "integer", "description": "search location codeoptional fieldif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: 2840Note: chat_gpt data is available for 2840 only", "nullable": true }, "language_name": { "type": "string", "description": "full name of search languageoptional fieldif you use this field, you don't need to specify language_code;if you don't specify this field, the language_code with en value will be used by default;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for English only", "nullable": true }, "language_code": { "type": "string", "description": "search language codeoptional fieldif you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: enNote: chat_gpt data is available for en onlyn", "nullable": true }, "platform": { "type": "string", "description": "target platformoptional fieldpossible values:chat_gpt, googledefault value: googleNote: the data returned depends on the selected platformNote #2:chat_gpt data is available for the United States and English only", "nullable": true }, "links_scope": { "type": "string", "description": "links source scopeoptional fieldthis parameter specifies which links will be used to extract domains and aggregation datapossible values: sources, search_resultsdefault value: sources", "nullable": true }, "initial_dataset_filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of filter expressions applied before aggregationoptional fieldyou can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_matchyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"ai_search_volume\",\">\",\"1000\"]The full list of possible filters is available here.", "nullable": true }, "items_list_limit": { "type": "integer", "description": "maximum number of results in the items arrayoptional fieldyou can use this parameter to limit the number of data objects you receive in the items arrayminimum value: 1maximum value: 10default value: 5", "nullable": true }, "internal_list_limit": { "type": "integer", "description": "maximum number of elements within internal arraysoptional fieldyou can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domainminimum value: 1maximum value: 10default value: 5", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "platform": "chat_gpt", "target": [ { "keyword": "bmw", "search_scope": [ "answer" ] }, { "keyword": "auto", "search_scope": [ "question" ], "match_type": "partial_match" } ], "links_scope": "sources", "initial_dataset_filters": [ [ "ai_search_volume", ">", 10 ] ], "items_list_limit": 3, "internal_list_limit": 2 } ] }, "AiOptimizationLlmMentionsTopPagesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsTopPagesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationLlmMentionsTopPagesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsTopPagesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationLlmMentionsTopPagesLiveResultInfo": { "type": "object", "properties": { "total": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationResultTotalInfo" } ], "description": "aggregated mentions metrics summarycontains overall aggregated LLM mention metrics across all found top pages, grouped by various dimensions", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionssLiveItem" } ], "nullable": true }, "description": "individual pages resultsarray containing detailed mention metrics for each of the found top pages", "nullable": true } } }, "AiOptimizationLlmMentionsCrossAggregatedMetricsLiveRequestInfo": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLLmMentionsCrossAggregateMetricsTargetInfo" } ], "nullable": true }, "description": "array of objects containing target entities with aggregation keys", "nullable": true }, "aggregation_key": { "type": "string", "description": "aggregation key for grouping the resultsrequired fieldgroups results for comparison and serves as a label for the group;you can specify up to 250 characters in the aggregation_key field" }, "target": { "type": "array", "items": { "type": "string" }, "description": "array of objects containing target entitiesrequired fielda single target can contain up to 10 domain and/or keyword entities" }, "domain_entity": { "type": "object", "description": "domain entity in the target arrayexample:{\"domain\": \"en.wikipedia.org\", \"search_filter\": \"exclude\", \"search_scope\": [\"sources\"]}", "nullable": true }, "domain": { "type": "string", "description": "target domainrequired field if you don't specify a keywordyou can specify up to 63 characters in the domain field;a domain should be specified without https:// and www.", "nullable": true }, "search_filter": { "type": "string", "description": "target keyword search filteroptional fieldpossible values:include, excludedefault value: include", "nullable": true }, "search_scope": { "type": "array", "items": { "type": "string" }, "description": "target keyword search scopeoptional fieldpossible values:any, question, answer, brand_entities, fan_out_queriesdefault value: any", "nullable": true }, "include_subdomains": { "type": "boolean", "description": "indicates if the subdomains of the target domain will be included in the searchoptional fieldif set to true, the subdomains will be included in the searchdefault value: false", "nullable": true }, "keyword_entity": { "type": "object", "description": "keyword entity in the target arrayexample:{\"keyword\": \"bmw\", \"search_filter\": \"include\", \"search_scope\": [\"question\"], \"match_type \": \"partial_match\"}", "nullable": true }, "keyword": { "type": "string", "description": "target keywordrequired field if you don't specify a domainyou can specify up to 250 characters in the keyword fieldall %## will be decoded (plus character \u2018+\u2019 will be decoded to a space character)if you need to use the \u201c%\u201d character for your keyword, please specify it as \u201c%25\u201d;if you need to use the \u201c+\u201d character for your keyword, please specify it as \u201c%2B\u201dlearn more about rules and limitations of keyword and keywords fields in DataForSEO APIs in this Help Center article", "nullable": true }, "match_type": { "type": "string", "description": "target keyword match typedefines how the specified keyword is matchedoptional fieldpossible values:word_match - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for \"light\" will return results with \"light bulb\", \"light switch\");partial_match - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for \"light\" will return results with \"lighting\", \"highlight\");default value: word_match", "nullable": true }, "location_name": { "type": "string", "description": "full name of search locationoptional fieldif you use this field, you don't need to specify location_codeif you don't specify this field, the location_code with 2840 value will be used by default;you can receive the list of available locations of the search engine with their location_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for United States only", "nullable": true }, "location_code": { "type": "integer", "description": "search location codeoptional fieldif you use this field, you don't need to specify location_nameyou can receive the list of available locations of the search engine with their location_code by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: 2840Note: chat_gpt data is available for 2840 only", "nullable": true }, "language_name": { "type": "string", "description": "full name of search languageoptional fieldif you use this field, you don't need to specify language_code;if you don't specify this field, the language_code with en value will be used by default;you can receive the list of available languages of the search engine with their language_name by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesNote: chat_gpt data is available for English only", "nullable": true }, "language_code": { "type": "string", "description": "search language codeoptional fieldif you use this field, you don't need to specify language_name;you can receive the list of available languages of the search engine with their language_code_by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languagesdefault value: enNote: chat_gpt data is available for en onlyn", "nullable": true }, "platform": { "type": "string", "description": "target platformoptional fieldpossible values:chat_gpt, googledefault value: googleNote: the data returned depends on the selected platformNote #2:chat_gpt data is available for the United States and English only", "nullable": true }, "initial_dataset_filters": { "type": "array", "items": { "type": "object", "nullable": true }, "description": "array of filter expressions applied before aggregationoptional fieldyou can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result;you can add several filters at once (8 filters maximum)you should set a logical operator and, or between the conditionsthe following operators are supported:=, <>, in, not_in, like, not_like, ilike, not_ilike, match, not_matchyou can use the % operator with like and not_like to match any string of zero or more charactersexample:[\"ai_search_volume\",\">\",\"1000\"]The full list of possible filters is available here.", "nullable": true }, "internal_list_limit": { "type": "integer", "description": "maximum number of elements within internal arraysoptional fieldyou can use this field to limit the number of elements within the following arrays:sources_domainsearch_results_domainminimum value: 1maximum value: 10default value: 5", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "language_code": "en", "location_code": 2840, "platform": "google", "targets": [ { "aggregation_key": "chat_gpt", "target": [ { "keyword": "chat gpt" } ] }, { "aggregation_key": "claude", "target": [ { "keyword": "claude" } ] }, { "aggregation_key": "gemini", "target": [ { "keyword": "gemini" } ] }, { "aggregation_key": "perplexity", "target": [ { "keyword": "perplexity", "search_filter": "include" } ] } ], "initial_dataset_filters": [ [ "ai_search_volume", ">", 10 ] ], "internal_list_limit": 5 } ] }, "AiOptimizationLLmMentionsCrossAggregateMetricsTargetInfo": { "type": "object", "properties": { "target": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLLmMentionsTargetElement" } ], "nullable": true }, "nullable": true }, "aggregation_key": { "type": "string", "description": "", "nullable": true } } }, "AiOptimizationChatGptLlmScraperTaskPostResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperTaskPostTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperTaskPostTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "object", "description": "array of results\nin this case, the value will be null", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationClaudeLlmResponsesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationClaudeLlmResponsesLiveResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "description": "number of reasoning tokenstotal count of tokens used to generate reasoning content", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was used", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "model": { "type": "string", "description": "indicates the model version", "nullable": true }, "check_url": { "type": "string", "description": "direct URL to search engine resultsyou can use it to make sure that we provided exact results", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true }, "search_results": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ChatgptSearchResult" } ], "nullable": true }, "description": "array of search resultsall web search outputs the model retrieved when looking up information, including duplicates and unused entries", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SourceInfo" } ], "nullable": true }, "description": "array of sourcesthe sources the model actually cited or relied on in its final answer", "nullable": true }, "fan_out_queries": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true }, "brand_entities": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/ChatGptBrandEntity" } ], "nullable": true }, "description": "array of brand entitiescontains information on brands mentioned in the response", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results", "format": "int64", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search resultscontains types of search results (items) found in SERP.possible item types:chat_gpt_text, chat_gpt_table, chat_gpt_navigation_list, chat_gpt_images, chat_gpt_local_businesses, chat_gpt_products", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseChatGptLlmScraperElementItem" } ], "nullable": true }, "description": "items present in the element", "nullable": true } } }, "AiOptimizationClaudeLlmResponsesLiveRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value: 1;maximum value: 4096;default value: 2048;Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limitNote #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse; lower values make output more focused;minimum value: 0maximum value: 1default value: 0.7Note: temperature cannot be used together with top_p in the same request", "nullable": true }, "top_p": { "type": "number", "description": "diversity of the AI responseoptional field controls diversity of the response by limiting token selection;minimum value: 0maximum value: 1 default value: nullNote: top_p cannot be used together with temperature in the same request", "nullable": true }, "web_search": { "type": "boolean", "description": "enable web search for current informationoptional fieldwhen enabled, the AI model can access and cite current web information;Note: refer to the Models endpoint for a list of models that support web_search; default value: false;The cost of the parameter can be calculated on the Pricing page", "nullable": true }, "force_web_search": { "type": "boolean", "description": "force AI agent to use web searchoptional fieldto enable this parameter, web_search must also be enabled;when enabled, the AI model is forced to access and cite current web information;default value: false;Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response", "nullable": true }, "web_search_country_iso_code": { "type": "string", "description": "ISO country code of the locationoptional fieldpossible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'", "nullable": true }, "web_search_city": { "type": "string", "description": "city name of the locationoptional fieldNote: specify web_search_country_iso_code to use this parameter", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behaviouroptional fielddefines the AI's role, tone, or specific behavior;you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "use_reasoning": { "type": "boolean", "description": "enable reasoning for the AI modeloptional fieldwhen enabled, the model will perform reasoning before generating a responserefer to the Models endpoint for a list of models that support reasoningdefault value: falseNote: if set to true, the minimum value for max_output_tokens is 1025Note #2: if set to true, force_web_search must be set to falseNote #3: if set to true, the temperature and top_p cannot be used", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "max_output_tokens": 200, "model_name": "claude-opus-4-0", "temperature": 0.3, "web_search": true, "web_search_country_iso_code": "FR", "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "AiOptimizationClaudeLlmResponsesTaskPostRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;for example, if claude-opus-4-0 is specified, the claude-opus-4-20250514 will be set as model_name automatically;you can receive the list of available LLM models by making a separate request to the https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value: 1;maximum value: 4096;default value: 2048;Note: if web_search is set to true or the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limitNote #2: if use_reasoning is set to true, the minimum value for max_output_tokens is 1025", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse; lower values make output more focused;minimum value: 0maximum value: 1default value: 0.7Note: temperature cannot be used together with top_p in the same request", "nullable": true }, "top_p": { "type": "number", "description": "diversity of the AI responseoptional field controls diversity of the response by limiting token selection;minimum value: 0maximum value: 1 default value: nullNote: top_p cannot be used together with temperature in the same request", "nullable": true }, "web_search": { "type": "boolean", "description": "enable web search for current informationoptional fieldwhen enabled, the AI model can access and cite current web information;Note: refer to the Models endpoint for a list of models that support web_search; default value: false;The cost of the parameter can be calculated on the Pricing page", "nullable": true }, "force_web_search": { "type": "boolean", "description": "force AI agent to use web searchoptional fieldto enable this parameter, web_search must also be enabled;when enabled, the AI model is forced to access and cite current web information;default value: false;Note: even if the parameter is set to true, there is no guarantee web sources will be cited in the response", "nullable": true }, "web_search_country_iso_code": { "type": "string", "description": "ISO country code of the locationoptional fieldpossible values: 'AR','AT','AU','BE','BR','CA','CH','CL','CN','DE','DK','ES','FI','FR','GB','HK','ID','IN','IT','JP','KR','MX','MY','NL','NO','NZ','PH','PL','PT','RU','SA','SE','TR','TW','US','ZA'", "nullable": true }, "web_search_city": { "type": "string", "description": "city name of the locationoptional fieldNote: specify web_search_country_iso_code to use this parameter", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behaviouroptional fielddefines the AI's role, tone, or specific behavior;you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "use_reasoning": { "type": "boolean", "description": "enable reasoning for the AI modeloptional fieldwhen enabled, the model will perform reasoning before generating a responserefer to the Models endpoint for a list of models that support reasoningdefault value: falseNote: if set to true, the minimum value for max_output_tokens is 1025Note #2: if set to true, force_web_search must be set to falseNote #3: if set to true, the temperature and top_p cannot be used", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true }, "postback_url": { "type": "string", "description": "URL for sending task resultsoptional fieldonce the task is completed, we will send a POST request with its results compressed in the gzip format to the postback_url you specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the request.example:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tagNote: special character in postback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true }, "pingback_url": { "type": "string", "description": "notification URL of a completed taskoptional fieldwhen a task is completed we will notify you by GET request sent to the URL you have specifiedyou can use the \u2018$id\u2019 string as a $id variable and \u2018$tag\u2019 as urlencoded $tag variable. We will set the necessary values before sending the requestexample:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tagNote: special character in pingback_url will be urlencoded;i.a., the # character will be encoded into %23learn more on our Help Center", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "max_output_tokens": 1024, "temperature": 0.3, "web_search_country_iso_code": "FR", "model_name": "claude-sonnet-4-0", "web_search": true, "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "AiOptimizationLlmMentionsAggregatedMetricsLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsAggregatedMetricsLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationLlmMentionsAggregatedMetricsLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationLlmMentionsAggregatedMetricsLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationLlmMentionsAggregatedMetricsLiveResultInfo": { "type": "object", "properties": { "total": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationResultTotalInfo" } ], "description": "aggregated mentions metrics summarycontains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions", "nullable": true }, "items": { "type": "object", "description": "individual pages resultsarray containing detailed mention metrics for each of the found top pagesin this case, equals null", "nullable": true } } }, "AiOptimizationChatGptLlmScraperLocationsResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLocationsTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLocationsTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationChatGptLlmScraperLocationsResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationChatGptLlmScraperLocationsResultInfo": { "type": "object", "properties": { "location_code": { "type": "integer", "description": "location code", "nullable": true }, "location_name": { "type": "string", "description": "full name of the location", "nullable": true }, "location_code_parent": { "type": "integer", "description": "the code of the superordinate locationexample:\"location_code\": 9041134,\"location_name\": \"Vienna International Airport,Lower Austria,Austria\",\"location_code_parent\": 20044where location_code_parent corresponds to:\"location_code\": 20044,\"location_name\": \"Lower Austria,Austria\"", "nullable": true }, "country_iso_code": { "type": "string", "description": "ISO country code of the location", "nullable": true }, "location_type": { "type": "string", "description": "location type", "nullable": true } } }, "AiOptimizationGeminiLlmScraperLiveAdvancedResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLiveAdvancedTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLiveAdvancedTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationGeminiLlmScraperLiveAdvancedResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationGeminiLlmScraperLiveAdvancedResultInfo": { "type": "object", "properties": { "keyword": { "type": "string", "description": "keyword received in a POST arraythe keyword is returned with decoded %## (plus symbol '+' will be decoded to a space character)", "nullable": true }, "location_code": { "type": "integer", "description": "location code in a POST array", "nullable": true }, "language_code": { "type": "string", "description": "language code in a POST array", "nullable": true }, "model": { "type": "string", "description": "indicates the model version", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "markdown": { "type": "string", "description": "content of the element in markdown formatcontent of the result formatted in the markdown markup language", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SourceInfo" } ], "nullable": true }, "description": "array of sourcesthe sources the model actually cited or relied on in its final answer", "nullable": true }, "se_results_count": { "type": "integer", "description": "total number of results", "format": "int64", "nullable": true }, "item_types": { "type": "array", "items": { "type": "string", "nullable": true }, "description": "types of search resultscontains types of search results (items) found in SERP.possible item types:gemini_text, gemini_table, gemini_images", "nullable": true }, "items_count": { "type": "integer", "description": "the number of results returned in the items array", "format": "int64", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseGeminiLlmScraperElementItem" } ], "nullable": true }, "description": "items present in the element", "nullable": true } } }, "AiOptimizationPerplexityLlmResponsesLiveRequestInfo": { "type": "object", "properties": { "user_prompt": { "type": "string", "description": "prompt for the AI modelrequired fieldthe question or task you want to send to the AI model;you can specify up to 500 characters in the user_prompt field" }, "model_name": { "type": "string", "description": "name of the AI modelrequired fieldmodel_nameconsists of the actual model name and version name;if the basic model name is specified, its latest version will be set by default;you can receive the list of available LLM models by making a separate request to the following endpoint: https://api.dataforseo.com/v3/ai_optimization/perplexity/llm_responses/models" }, "max_output_tokens": { "type": "integer", "description": "maximum number of tokens in the AI responseoptional fieldminimum value: 1maximum value: 4096;default value: 2048;Note: if the reasoning model is specified in the request, the output token count may exceed the specified max_output_tokens limit", "nullable": true }, "temperature": { "type": "number", "description": "randomness of the AI responseoptional fieldhigher values make output more diverse lower values make output more focusedminimum value: 0maximum value: 1.9default value: 0.77", "nullable": true }, "top_p": { "type": "number", "description": "diversity of the AI responseoptional field controls diversity of the response by limiting token selectionminimum value: 0maximum value: 1 default value: 0.9", "nullable": true }, "web_search_country_iso_code": { "type": "string", "description": "country code for web search localizationoptional fieldspecify the country ISO code to get localized web search resultsNote: available only for Perplexity Sonar modelsexample: US", "nullable": true }, "system_message": { "type": "string", "description": "instructions for the AI behavioroptional fielddefines the AI's role, tone, or specific behavior you can specify up to 500 characters in the system_message field", "nullable": true }, "message_chain": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageChainItem" } ], "nullable": true }, "description": "conversation history\noptional field\narray of message objects representing previous conversation turns;\neach object must contain:\nrole string with either user or ai role;\nmessage string with message content (max 500 characters);\nyou can specify maximum of 10 message objects in the array;\nNote: for Perplexity models, messages must strictly alternate between user and AI roles (user \u2192 ai);\nexample:\n\"message_chain\": [{\"role\":\"user\",\"message\":\"Hello, what\u2019s up?\"},{\"role\":\"ai\",\"message\":\"Hello! I\u2019m doing well, thank you. How can I assist you today?\"}]", "nullable": true }, "tag": { "type": "string", "description": "user-defined task identifieroptional fieldthe character limit is 255you can use this parameter to identify the task and match it with the resultyou will find the specified tag value in the data object of the response", "nullable": true } }, "example": [ { "system_message": "communicate as if we are in a business meeting", "message_chain": [ { "role": "user", "message": "Hello, what\u2019s up?" }, { "role": "ai", "message": "Hello! I\u2019m doing well, thank you. How can I assist you today? Are there any specific topics or projects you\u2019d like to discuss in our meeting?" } ], "max_output_tokens": 200, "temperature": 0.3, "top_p": 0.5, "web_search_country_iso_code": "FR", "model_name": "sonar", "user_prompt": "provide information on how relevant the amusement park business is in France now" } ] }, "AiOptimizationPerplexityLlmResponsesLiveResponseInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationPerplexityLlmResponsesLiveTaskInfo" } ], "nullable": true }, "description": "array of tasks", "nullable": true } } } ] }, "AiOptimizationPerplexityLlmResponsesLiveTaskInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AiOptimizationPerplexityLlmResponsesLiveResultInfo" } ], "nullable": true }, "description": "array of results", "nullable": true } } } ] }, "AiOptimizationPerplexityLlmResponsesLiveResultInfo": { "type": "object", "properties": { "model_name": { "type": "string", "description": "name of the AI model used", "nullable": true }, "input_tokens": { "type": "integer", "description": "number of tokens in the inputtotal count of tokens processed", "nullable": true }, "output_tokens": { "type": "integer", "description": "number of tokens in the outputtotal count of tokens generated in the AI response", "nullable": true }, "reasoning_tokens": { "type": "integer", "nullable": true }, "web_search": { "type": "boolean", "description": "indicates if web search was usedNote: web search is enabled by default in Perplexity Sonar models", "nullable": true }, "money_spent": { "type": "number", "description": "cost of AI tokens, USDthe price charged by the third-party AI model provider for according to its Pricing", "nullable": true }, "datetime": { "type": "string", "description": "date and time when the result was receivedin the UTC format: \u201cyyyy-mm-dd hh-mm-ss +00:00\u201dexample:2019-11-15 12:57:46 +00:00", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/MessageAiOptimizationLlmResponseElementItem" } ], "nullable": true }, "description": "array of response itemscontains structured AI response data", "nullable": true }, "fan_out_queries": { "type": "object", "description": "array of fan-out queriescontains related search queries derived from the main query to provide a more comprehensive response", "nullable": true } } }, "MessageAiOptimizationLlmResponseElementItem": { "type": "object", "allOf": [ { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/BaseAiOptimizationLlmResponseElementItem" } ], "nullable": true }, { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/LlmMessageSectionInfo" } ], "nullable": true }, "description": "reasoning chain sectionsarray of objects containing the reasoning chain sections generated by the LLM", "nullable": true } } } ] }, "LlmMessageSectionInfo": { "type": "object", "properties": { "type": { "type": "string", "description": "type of element", "nullable": true }, "text": { "type": "string", "description": "AI-generated text content", "nullable": true }, "annotations": { "type": "array", "items": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/AnnotationInfo" } ], "nullable": true }, "description": "array of references used to generate the responseequals null if the web_search parameter is not set to trueNote: annotations may return empty even when web_search is true, as the AI will attempt to retrieve web information but may not find relevant results", "nullable": true } } }, "AnnotationInfo": { "type": "object", "properties": { "title": { "type": "string", "description": "the domain name or title of the quoted source", "nullable": true }, "url": { "type": "string", "description": "URL of the quoted source", "nullable": true } } } } }