Send a question and get back the pages on the web most relevant to it, ranked, each with its title and an excerpt, for 1.5 credits.
Your agent can read any page, but first it has to find the right one. Search takes a question and returns the pages on the web most relevant to it, ranked, each with its URL, its title, an excerpt and a score. Each search costs 1.5 credits.
Search reads no page. Each excerpt is the passage of the page most relevant to your query, enough to decide which page to open. To read a page, pass its URL to Fetch, or ask it your question with Highlights. Search, then fetch shows both.
Your first search
import { ExpandClient } from '@expandai/sdk'const expand = new ExpandClient()const { results } = await expand.search({ query: 'how do I rotate a Stripe API key', maxResults: 3 })
expandai search "how do I rotate a Stripe API key" --max-results 3
// Arguments for the search tool{ "query": "how do I rotate a Stripe API key", "maxResults": 3}
curl https://api.expand.ai/v1/search \ -H "x-expand-api-key: $EXPAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"how do I rotate a Stripe API key","maxResults":3}'
To get an API key and run this yourself, follow the Quickstart.
The settings:
Setting
Definition
Default
query
What to search for, as a question or keywords, up to 2,000 characters. Spaces at either end are removed.
Required
maxResults
The most results to return, from 1 to 10. You may get fewer.
10
What you get back
{ "id": "019a2b7c-4e1f-7d3a-9b2e-5c8f1a6d4e20", "query": "how do I rotate a Stripe API key", "results": [ { "url": "https://docs.stripe.com/keys", "title": "API keys | Stripe Documentation",
The results come back best first, one per page. title and excerpt are empty strings when the web results have none for the page. A query with no matches returns an empty results list. If ranking is briefly unavailable, the results still come back in the web results' order, and score only gives that order.
Note
An excerpt is the web's excerpt of the page, not the page, and carries no citation back to it. To read a page, or for cited evidence, fetch it.
Reading a search back
Every search is saved with its results for 90 days. To read one again, send its id:
You get the same response back. Reading a search is free and does not search again. Only your organization can read its searches. Any other id returns 404.
Tuning the results
Search asks the web for twenty results, ranks them against your query, and returns the best maxResults in score order. One kind of query keeps the web's order instead: a query looking for pages that are things, such as grants, vendors or products, rather than pages that answer a question, because ranking favours pages about the things over the things themselves.
Try a full question. If keywords such as stripe api key miss, try how do I rotate a Stripe API key.
Start with a few results. Lower maxResults to read less, and raise it if the page you need is not there.
Use score to order one search. It orders the results of one search.
Credit usage
A search costs 1.5 credits. A search that fails, or finds nothing, costs nothing. See Pricing & Usage.
API reference: the request and response, field by field.
"
excerpt
"
:
"On the API keys page, click the overflow menu ( ) for the key you want to rotate. Select Rotate key. Select an expiration date from the Expiration dropdown. ..."
"title": "Stripe - How to Rotate Leaked API Keys",
"excerpt": "This tutorial provides step-by-step instructions on how to rotate a Stripe API key. Generate a new Stripe API key Step 1 - Navigate to the API key page ...",
"title": "How do I rotate/change/update my Stripe API key?",
"excerpt": "Rotating a key revokes it and generates a replacement key. You can rotate a key immediately or schedule a key to rotate after a certain time. See the technical ...",
"score": 0.991
}
]
}
The page's title.
results[].excerpt
The passage of the page most relevant to your query, as the web results give it.
results[].score
How well the result matches your query. Higher is better.
403
Your organization is blocked or out of credits. Nothing is charged.
No
404
Reading a search back, the id is not one of your organization's searches.
No
500
Search could not run.
Yes. The body says retryable: true, and the SDK retries it for you.