DataForSEO · Schema
DataForSEO Ai Optimization API Schemas
SEOSERPKeywordsBacklinksDomain AnalyticsOn-Page SEOCompetitor ResearchSearch EnginesContent AnalysisE-CommerceApp StoreBusiness DataAI OptimizationSocial Media
JSON Schema
{
"$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": {
# --- truncated at 32 KB (262 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dataforseo/refs/heads/main/json-schema/dataforseo-ai-optimization-schema.json