> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Links

> Get every link on a page as a list of absolute URLs, menus and footers included. Use it to find the next pages to read. $1 per 1,000 pages.

`links` returns every link on the page as an absolute URL, in page order.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request lists the links of a small page.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.iana.org/help/example-domains",
    "formats": ["links"]
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.iana.org/help/example-domains",
    formats: ["links"],
  }),
});
const { data } = await response.json();
console.log(data.links.length);
console.log(data.links.slice(0, 5));
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://www.iana.org/help/example-domains",
        "formats": ["links"],
    },
)
data = response.json()["data"]
print(len(data["links"]))
print(data["links"][:5])
```

## Read the response

`data.links` is an array of strings. This page has 26 links. The real response is cut to the first four.

```json theme={null}
{
  "success": true,
  "data": {
    "links": [
      "https://www.iana.org/",
      "https://www.iana.org/domains",
      "https://www.iana.org/protocols",
      "https://www.iana.org/numbers"
    ],
    "metadata": {
      "title": "Example Domains",
      "sourceURL": "https://www.iana.org/help/example-domains",
      "url": "https://www.iana.org/help/example-domains",
      "statusCode": 200,
      "contentType": "text/html",
      "cacheState": "miss",
      "scrapeId": "61ae432b-8a05-43fc-b8bf-90d4cc017ba4",
      "costUsd": 0.001
    }
  },
  "id": "61ae432b-8a05-43fc-b8bf-90d4cc017ba4",
  "costUsd": 0.001,
  "requestId": "61ae432b-8a05-43fc-b8bf-90d4cc017ba4"
}
```

Links come from the whole page, so the list includes menus, headers and footers even when `onlyMainContent` is `true`. Links inside the Markdown follow `linkStyle` instead. See [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md).

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `formats` | `array` | `["markdown"]` | Add `"links"` to return every link on the page. |

## Limits and errors

* A PDF comes back as Markdown only. Asking for `links` on a PDF returns `400 invalidRequest`.
* A page that answers with a 404 or 410 status, or cannot be read, costs nothing.

## Price

\$1 per 1,000 pages. `links` adds nothing to the price of the page.

## Related

* [Map](https://docs.stophy.dev/map/overview) lists the pages of a whole site without reading them.
* [Crawl](https://docs.stophy.dev/crawl/overview) follows links and reads every page of a site.
* [Images](https://docs.stophy.dev/scrape/images.md) lists the image URLs on a page.
* [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md) controls how links appear in the Markdown.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.