Skip to content
Free$1 of credit for every new organization
All articles

Guide

Give your model the live web: search, read, cite

Models only know what they were trained on. Here's the three-call pattern for answering from current sources, with citations, on one API key.

· 2 min read · Usefully team


A language model answers from what it learned during training. Ask about last week's release, today's price or a page it has never seen, and it either guesses or says it doesn't know. The fix is to hand it the sources: search the web, read the best pages, and ask the model to answer from them.

On Usefully all three steps use the same API key and the same balance, and every call shows up in your logs with its cost.

1. Search

POST /v1/search returns titles, URLs, short snippets and, when known, publish dates. Add include_content to get each page's main text in the same call, which is usually all you need.

curl https://api.usefully.info/v1/search \
  -H "Authorization: Bearer $USEFULLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "postgres 18 new features", "num_results": 5, "include_content": true}'

Useful options: freshness (day, week, month or year) for anything recent, and include_domains to search only sites you trust. Each result's content is up to 5,000 characters by default; raise it with max_content_chars (up to 50,000).

2. Read (when a snippet isn't enough)

If you already have URLs, or need a page in full, POST /v1/extract returns the main text of up to 10 pages per call. A page that can't be fetched comes back as failed and isn't billed.

curl https://api.usefully.info/v1/extract \
  -H "Authorization: Bearer $USEFULLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/release-notes"], "max_chars": 20000}'

3. Answer, with citations

Number the sources, put them in the prompt, and tell the model to answer from them only. Because Usefully speaks the OpenAI API, the standard SDK works with a different base URL.

import os, requests
from openai import OpenAI

KEY = os.environ["USEFULLY_API_KEY"]
client = OpenAI(base_url="https://api.usefully.info/v1", api_key=KEY)

def answer(question: str) -> str:
    hits = requests.post(
        "https://api.usefully.info/v1/search",
        headers={"Authorization": f"Bearer {KEY}"},
        json={"query": question, "num_results": 5, "include_content": True},
    ).json()["results"]
    sources = "\n\n".join(
        f"[{i}] {h['title']} ({h['url']})\n{h.get('content') or h['snippet']}"
        for i, h in enumerate(hits, 1)
    )
    reply = client.chat.completions.create(
        model="anthropic/claude-sonnet-5-5",
        messages=[
            {"role": "system", "content": "Answer from the sources only. Cite them like [1]. Say so if they don't answer the question."},
            {"role": "user", "content": f"{question}\n\nSources:\n{sources}"},
        ],
    )
    return reply.choices[0].message.content

Tips

  • Keep the prompt focused. Five good sources beat twenty mediocre ones, and cost less.
  • Ask for "I don't know". Telling the model to say when the sources don't answer the question cuts down made-up answers.
  • Show the sources. Return the URLs with the answer so people can check them.
  • Use freshness for news. "freshness": "week" keeps old pages out of time-sensitive questions.

Full details are in the search guide and reading pages.

More articles

Get started

Your first request is five minutes away.

  • $1 of free credit to start
  • No card, no subscription
  • Keep the SDK you already use
  • Real people at support@usefully.info
Give your model the live web: search, read, cite · Usefully