Web search

web_search runs against a search instance this platform operates itself — nothing here calls out to a third-party search API. Results are deduplicated to one per domain before the model ever sees them, so a question about a statute does not come back as the same aggregator site eight times over.

What this costs

Metered per search — one charge each time the model actually calls web_search, regardless of how many results come back. Pricing is set by your platform operator and may not be published yet — check Pricing.

Declaring it

tools

[{ "type": "web_search" }]

That is the whole declaration — no ids, no configuration. When it calls the tool, the model itself chooses the arguments below.

Parameter	Type	Description
query Required	string	What the model searches for.
count Optional	integer	How many results to return. Default: `6`
lang Optional	string	`fa`, `en` or `es` to narrow the search to one language; left empty, it is unrestricted.

What comes back

The raw result list is not handed to you over the API — it goes to the model, and only the model's finished answer comes back in choices[0].message.content. If you need the sources visible, ask for them: a system message telling the model to list the URL for every claim works, because the titles, URLs and snippets below are exactly what it has to work with.

What the model sees

{
  "query": "latest Python release",
  "results": [
    { "title": "Python 3.13 release notes",
      "url": "https://docs.python.org/3/whatsnew/3.13.html",
      "snippet": "…" },
    { "title": "Download Python",
      "url": "https://www.python.org/downloads/",
      "snippet": "…" }
  ]
}

Complete example

One request. The model is larsa-auto — the only model on this platform that runs web_search server-side.

curl https://api.console.larsa.larsima.com/v1/chat/completions \
  -H "Authorization: Bearer $LARSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "larsa-auto",
    "messages": [
      {"role": "system", "content":
        "List the source URL after every claim you make from a search."},
      {"role": "user", "content":
        "What is the latest stable Python release?"}
    ],
    "tools": [{"type": "web_search"}]
  }'

import os
import requests

API = "https://api.console.larsa.larsima.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['LARSA_API_KEY']}",
           "Content-Type": "application/json"}

res = requests.post(f"{API}/chat/completions", headers=HEADERS, json={
    "model": "larsa-auto",
    "messages": [
        {"role": "system", "content":
            "List the source URL after every claim you make "
            "from a search."},
        {"role": "user", "content":
            "What is the latest stable Python release?"},
    ],
    "tools": [{"type": "web_search"}],
})
print(res.json()["choices"][0]["message"]["content"])

const API = "https://api.console.larsa.larsima.com/v1";

const res = await fetch(`${API}/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LARSA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "larsa-auto",
    messages: [
      { role: "system", content:
        "List the source URL after every claim you make " +
        "from a search." },
      { role: "user", content:
        "What is the latest stable Python release?" },
    ],
    tools: [{ type: "web_search" }],
  }),
});
const out = await res.json();
console.log(out.choices[0].message.content);

const API = "https://api.console.larsa.larsima.com/v1";

const res = await fetch(`${API}/chat/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LARSA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "larsa-auto",
    messages: [
      { role: "system", content:
        "List the source URL after every claim you make " +
        "from a search." },
      { role: "user", content:
        "What is the latest stable Python release?" },
    ],
    tools: [{ type: "web_search" }],
  }),
});
const out = (await res.json()) as any;
console.log(out.choices[0].message.content);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "larsa-auto",
		"messages": []map[string]string{
			{"role": "system", "content":
				"List the source URL after every claim you make " +
					"from a search."},
			{"role": "user", "content":
				"What is the latest stable Python release?"},
		},
		"tools": []map[string]string{{"type": "web_search"}},
	})
	req, _ := http.NewRequest("POST",
		"https://api.console.larsa.larsima.com/v1/chat/completions",
		bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LARSA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	raw, _ := io.ReadAll(resp.Body)
	var out map[string]any
	json.Unmarshal(raw, &out)
	choice := out["choices"].([]any)[0].(map[string]any)
	fmt.Println(choice["message"].(map[string]any)["content"])
}

use serde_json::json;
use std::env;

fn main() {
    let key = env::var("LARSA_API_KEY").unwrap();
    let client = reqwest::blocking::Client::new();
    let out: serde_json::Value = client
        .post("https://api.console.larsa.larsima.com/v1/chat/completions")
        .bearer_auth(key)
        .json(&json!({
            "model": "larsa-auto",
            "messages": [
                {"role": "system", "content":
                    "List the source URL after every claim you make from a search."},
                {"role": "user", "content":
                    "What is the latest stable Python release?"}
            ],
            "tools": [{"type": "web_search"}]
        }))
        .send().unwrap().json().unwrap();
    println!("{}", out["choices"][0]["message"]["content"]);
}

import org.json.JSONArray;
import org.json.JSONObject;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class WebSearchExample {
    public static void main(String[] args) throws Exception {
        JSONObject body = new JSONObject()
            .put("model", "larsa-auto")
            .put("messages", new JSONArray()
                .put(new JSONObject().put("role", "system")
                    .put("content",
                        "List the source URL after every claim you make from a search."))
                .put(new JSONObject().put("role", "user")
                    .put("content",
                        "What is the latest stable Python release?")))
            .put("tools", new JSONArray().put(
                new JSONObject().put("type", "web_search")));

        HttpRequest req = HttpRequest.newBuilder(URI.create(
                "https://api.console.larsa.larsima.com/v1/chat/completions"))
            .header("Authorization", "Bearer " + System.getenv("LARSA_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body.toString()))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        JSONObject out = new JSONObject(res.body());
        System.out.println(out.getJSONArray("choices")
            .getJSONObject(0).getJSONObject("message")
            .getString("content"));
    }
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json.Nodes;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer",
        Environment.GetEnvironmentVariable("LARSA_API_KEY"));

var body = new JsonObject {
    ["model"] = "larsa-auto",
    ["messages"] = new JsonArray {
        new JsonObject { ["role"] = "system", ["content"] =
            "List the source URL after every claim you make " +
            "from a search." },
        new JsonObject { ["role"] = "user", ["content"] =
            "What is the latest stable Python release?" },
    },
    ["tools"] = new JsonArray {
        new JsonObject { ["type"] = "web_search" },
    },
};

var res = await http.PostAsync(
    "https://api.console.larsa.larsima.com/v1/chat/completions",
    new StringContent(body.ToJsonString(), Encoding.UTF8,
        "application/json"));
var out = JsonNode.Parse(
    await res.Content.ReadAsStringAsync())!.AsObject();
Console.WriteLine(out["choices"]![0]!["message"]!["content"]);

<?php

$ch = curl_init("https://api.console.larsa.larsima.com/v1/chat/completions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("LARSA_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "model" => "larsa-auto",
        "messages" => [
            ["role" => "system", "content" =>
                "List the source URL after every claim you make " .
                "from a search."],
            ["role" => "user", "content" =>
                "What is the latest stable Python release?"],
        ],
        "tools" => [["type" => "web_search"]],
    ]),
]);
$out = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $out["choices"][0]["message"]["content"], "\n";

require "json"
require "net/http"
require "uri"

uri = URI("https://api.console.larsa.larsima.com/v1/chat/completions")
req = Net::HTTP::Post.new(uri,
  "Authorization" => "Bearer #{ENV.fetch('LARSA_API_KEY')}",
  "Content-Type" => "application/json")
req.body = {
  model: "larsa-auto",
  messages: [
    { role: "system", content:
      "List the source URL after every claim you make "\
      "from a search." },
    { role: "user", content:
      "What is the latest stable Python release?" },
  ],
  tools: [{ type: "web_search" }],
}.to_json

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)["choices"][0]["message"]["content"]

File searchRetrieval over your own uploaded documents.Code interpreterReal computation, not an estimate.

Declaring it#

What comes back#

Complete example#

Declaring it

What comes back

Complete example