AiOptimization

Changed on

‌‌ Live Claude LLM Responses endpoint allows you to retrieve structured responses from a specific Claude model, based on the input parameters.

post/v3/ai_optimization/claude/llm_responses/live

Request

  • Base URL: https://api.dataforseo.com
  • URL: https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/live
  • Auth: HTTP basic

Request body

user_promptstring

<em>prompt for the AI model</em><br><strong>required field</strong><br>the question or task you want to send to the AI model;<br>you can specify <strong>up to 500 characters</strong> in the <code>user_prompt</code> field

model_namestring

<em>name of the AI model</em><br><strong>required field</strong><br><code>model_name</code >consists of the actual model name and version name;<br>if the basic model name is specified, its latest version will be set by default;<br>for example, if <code>claude-opus-4-0</code> is specified, the <code>claude-opus-4-20250514</code> will be set as <code>model_name</code> automatically;<br>you can receive the list of available LLM models by making a separate request to the <code>https://api.dataforseo.com/v3/ai_optimization/claude/llm_responses/models</code>

max_output_tokensinteger nullable

<em>maximum number of tokens in the AI response</em><br>optional field<br>minimum value: <code>1</code>;<br>maximum value: <code>4096</code>;<br>default value: <code>2048</code>;<br><strong>Note:</strong> if <code>web_search</code> is set to <code>true</code> or the reasoning model is specified in the request, the output token count may exceed the specified <code>max_output_tokens</code> limit<br><strong>Note #2:</strong> if <code>use_reasoning</code> is set to <code>true</code>, the minimum value for <code>max_output_tokens</code> is <code>1025</code>

temperaturenumber nullable

<em>randomness of the AI response</em><br>optional field<br>higher values make output more diverse; <br>lower values make output more focused;<br>minimum value: <code>0</code><br>maximum value: <code>1</code><br>default value: <code>0.7</code><p><strong>Note:</strong> <code>temperature</code> cannot be used together with <code>top_p</code> in the same request

top_pnumber nullable

<em>diversity of the AI response</em><br>optional field <br>controls diversity of the response by limiting token selection;<br>minimum value: <code>0</code><br>maximum value: <code>1</code> <br>default value: <code>null</code><p><strong>Note:</strong> <code>top_p</code> cannot be used together with <code>temperature</code> in the same request

web_searchboolean nullable

<em>enable web search for current information</em><br>optional field<br>when enabled, the AI model can access and cite current web information;<br><strong>Note:</strong> refer to the <a href="https://docs.dataforseo.com/v3/ai_optimization/claude/llm_responses/models/">Models endpoint</a> for a list of models that support <code>web_search</code>; <br>default value: <code>false</code>;<br>The cost of the parameter can be calculated on the <a title="Anthropic API Pricing" href="https://docs.anthropic.com/en/docs/about-claude/pricing" target="_blank" rel="noopener noreferrer">Pricing</a> page

force_web_searchboolean nullable

<em>force AI agent to use web search</em><br>optional field<br>to enable this parameter, <code>web_search</code> must also be enabled;<br>when enabled, the AI model is forced to access and cite current web information;<br>default value: <code>false</code>;<br><strong>Note:</strong> even if the parameter is set to <code>true</code>, there is no guarantee web sources will be cited in the response

web_search_country_iso_codestring nullable

<em>ISO country code of the location used for searching the web</em><br>optional field<br>possible values: <code>'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'</code>

web_search_citystring nullable

<em>city name of the location used for searching the web</em><br>optional field<br>

system_messagestring nullable

<em>instructions for the AI behaviour</em><br>optional field<br>defines the AI's role, tone, or specific behavior;<br>you can specify <strong>up to 500 characters</strong> in the <code>system_message</code> field

use_reasoningboolean nullable

<em>enable reasoning for the AI model</em><br>optional field<br>when enabled, the model will perform reasoning before generating a response<br>refer to the <a href="https://docs.dataforseo.com/v3/ai_optimization/claude/llm_responses/models/" target="_blank">Models endpoint</a> for a list of models that support <code>reasoning</code><br>default value: <code>false</code><br><strong>Note:</strong> if set to <code>true</code>, the minimum value for <code>max_output_tokens</code> is <code>1025</code><br><strong>Note #2:</strong> if set to <code>true</code>, <code>force_web_search</code> must be set to <code>false</code><br><strong>Note #3:</strong> if set to <code>true</code>, the <code>temperature</code> and <code>top_p</code> cannot be used

tagstring nullable

<em>user-defined task identifier</em><br>optional field<br><em>the character limit is 255</em><br>you can use this parameter to identify the task and match it with the result<br>you will find the specified <code>tag</code> value in the <code>data</code> object of the response

Example request

[
  {
    "system_message": "communicate as if we are in a business meeting",
    "message_chain": [
      {
        "role": "user",
        "message": "Hello, what’s up?"
      },
      {
        "role": "ai",
        "message": "Hello! I’m doing well, thank you. How can I assist you today? Are there any specific topics or projects you’d like to discuss in our meeting?"
      }
    ],
    "max_output_tokens": 200,
    "model_name": "claude-opus-5",
    "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"
  }
]

Response

Successful operation

versionstring nullable

the current version of the API

status_codeinteger nullable

general status code you can find the full list of the response codes here

status_messagestring nullable

general informational message you can find the full list of general informational messages here

timestring nullable

total execution time, seconds

costnumber double nullable

total tasks cost, USD

tasks_countinteger nullable

the number of tasks in the tasks array

tasks_errorinteger nullable

the number of tasks in the tasks array returned with an error

Changes

  • 6061f0e837b7Revision changes
    • breaking

      added to the /////////////////// response property oneOf list for the response status

    • info

      added the new optional request property /////

    • info

      added the optional property ////////////////// to the response with the status

    • info

      removed from the /////////////////// response property oneOf list for the response status

  • be20fca9d9ccRevision changes
    • info

      api operation id AiOptimizationClaudeLlmResponsesLive removed and replaced with ClaudeLlmResponsesLive

    • info

      added the optional property ////////////////// to the response with the status