# Choosing an endpoint

> Match a Search1API endpoint to the information you have and the result you need.

Canonical URL: https://s1.dev/docs/guides/choosing-an-endpoint

Start with two questions:

1. Do you have a topic, a URL, or an entire site?
2. Do you need links, readable text, structured fields, or a list of pages?

## Endpoint map

| Your starting point | What you need | Use |
| --- | --- | --- |
| A topic or question | Ranked web pages | [`POST /search`](https://s1.dev/docs/basic/search) |
| A topic or question | Ranked pages plus full text | [`POST /search`](https://s1.dev/docs/basic/search) with `crawl_results` |
| A question in plain language | Relevant results from the engines it calls for | [`POST /ask`](https://s1.dev/docs/basic/ask) |
| A current event | Recent coverage from news sources | [`POST /news`](https://s1.dev/docs/basic/news) |
| One URL | Readable page content | [`POST /crawl`](https://s1.dev/docs/basic/crawl) |
| One URL | A rendered PNG, JPEG, or WebP image | [`POST /screenshot`](https://s1.dev/docs/basic/screenshot) |
| One URL | Fields that match a JSON Schema | [`POST /extract`](https://s1.dev/docs/advanced/extract) |
| One site | A list of its URLs | [`POST /sitemap`](https://s1.dev/docs/advanced/sitemap) |
| One site | Content from many pages | [`POST /deepcrawl`](https://s1.dev/docs/advanced/deepcrawl) |
| No query | GitHub or Hacker News trends | [`POST /trending`](https://s1.dev/docs/advanced/trending) |

## Topic or URL: search vs. crawl

Use `/search` when you need to discover relevant pages. Use `/crawl` when you already know which page to read.

When you begin with a topic but also need source text, set `crawl_results` on `/search`. Search1API will crawl the top results in the same request. See [Improving search results](https://s1.dev/docs/guides/improving-search-results#read-the-results-not-just-the-snippets) for the request pattern.

`/crawl` works on any public URL. For a small set of mainstream sites, dedicated parsers or feed paths return cleaner, more structured output than generic extraction — see [Dedicated site parsers](https://s1.dev/docs/guides/site-parsers).

## Choosing engines yourself: search vs. ask

Use `/search` when you know which engine to query and what keywords to send. It returns that engine's ranking as is.

Use `/ask` when the right sources depend on the question, such as community discussion, code, papers, or video. It picks up to five engines and a time window, searches them in parallel, and keeps only results judged relevant, so an agent reads fewer off-topic results and spends fewer tokens. It costs 5 credits per request, compared with 1 for `/search`.

## Text or fields: crawl vs. extract

Use `/crawl` when a model or person will read the page as text: summarization, question answering, or RAG ingestion.

Use `/extract` when your application needs typed fields in a predictable shape. You provide the URL, an extraction prompt, and a JSON Schema; the endpoint returns data that follows that schema.

If you plan to crawl a page and immediately ask a model to convert it into fields, `/extract` combines those steps.

## Page content or pixels: crawl vs. screenshot

Use `/crawl` when you need the page as readable text for an agent, search index, summary, or RAG pipeline.

Use `/screenshot` when layout and visual state matter: link previews, visual regression inputs, archived page images, or vision-model input. It renders the page in a managed browser and returns image bytes directly.

## URL list or site content: sitemap vs. deepcrawl

Use `/sitemap` to discover which URLs a site contains. It returns links synchronously and is useful when your application will decide what to fetch next.

Use `/deepcrawl` when you need content from many pages. It runs asynchronously: the start request returns `202 Accepted` with a `taskId`, and you poll `GET /deepcrawl/status/{taskId}` until the task finishes.

## Web coverage or recent reporting: search vs. news

Use `/search` for general web discovery. Use `/news` when recency and news-specific sources are central to the task. Both endpoints support `time_range`, but they search different source sets.

## A common agent workflow

For research and answer-generation agents:

1. Start with `/search` and a small `crawl_results` value to collect ranked sources and readable text.
2. Use `/crawl` when you need to revisit a specific URL as text, or `/screenshot` when the workflow needs its visual state.
3. Use `/extract` when the output must follow a stable data schema.

Review [Credits and limits](https://s1.dev/docs/essentials/credits-and-limits) before choosing crawl depth or running the workflow in a batch.