> ## 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.

# Page metadata

> Read the title, description, language, social preview tags and status code of a page. Every Scrape response carries them, whatever formats you ask for.

Every Scrape response has a `data.metadata` object, whatever you list in `formats`. It describes the page itself: its title, description, language, social preview tags, status code, and what the call cost. A field is left out when the page does not have it, so check that a field is there before you use it.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request reads a docs page. It asks for `markdown` so the response has something besides `metadata`.

```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://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404",
    "formats": ["markdown"]
  }'
```

```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://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404",
    formats: ["markdown"],
  }),
});
const { data } = await response.json();
console.log(data.metadata.title);
console.log(data.metadata.ogImage);
```

```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://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404",
        "formats": ["markdown"],
    },
)
metadata = response.json()["data"]["metadata"]
print(metadata["title"])
print(metadata.get("ogImage"))
```

## Read the response

This real response is cut. The Markdown is shortened, and a few of the page's meta tags are left out.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# 404 Not Found\n\nThe HTTP **`404 Not Found`** [client error response](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#client_error_responses) status code indicates that…",
    "metadata": {
      "title": "404 Not Found - HTTP | MDN",
      "description": "The HTTP 404 Not Found client error response status code indicates that the server cannot find the requested resource. Links that lead to a 404 page are often called broken or dead links and can be subject to link rot.",
      "language": "en-US",
      "ogImage": "https://developer.mozilla.org/mdn-social-image.46ac2375.png",
      "favicon": "https://developer.mozilla.org/favicon.ico",
      "ogTitle": "404 Not Found - HTTP | MDN",
      "ogSiteName": "MDN Web Docs",
      "ogLocale": "en_US",
      "og:title": "404 Not Found - HTTP | MDN",
      "og:site_name": "MDN Web Docs",
      "twitter:card": "summary",
      "sourceURL": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404",
      "url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404",
      "statusCode": 200,
      "contentType": "text/html",
      "cacheState": "miss",
      "scrapeId": "8a9177f7-6923-4893-99d4-e357ffb5793f",
      "creditsUsed": 1,
      "costUsd": 0.001
    }
  },
  "id": "8a9177f7-6923-4893-99d4-e357ffb5793f",
  "costUsd": 0.001,
  "creditsUsed": 1,
  "requestId": "8a9177f7-6923-4893-99d4-e357ffb5793f"
}
```

The same tag can appear twice: once under a plain name such as `ogTitle`, and once under the tag's own name such as `og:title`. Use the plain names when they exist.

## Fields

| Field | Type | What it holds |
| - | - | - |
| `title` | `string` | The page title. |
| `description` | `string` | The page description. |
| `language` | `string` | The page language, such as `en-US`. |
| `ogImage` | `string` | The preview image the page names. |
| `favicon` | `string` | The page icon. |
| `sourceURL` | `string` | The URL you sent. |
| `url` | `string` | The URL the page ended up at after redirects. |
| `statusCode` | `number` | The HTTP status the page answered with. |
| `contentType` | `string` | What the page is, such as `text/html`, `application/pdf` or `text/csv`. |
| `cacheState` | `string` | `hit`, `miss` or `stale`. See [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md). |
| `cachedAt` | `string` | When the stored copy was made. Only on `hit` and `stale`. |
| `scrapeId` | `string` | The id of this read. Use it with `GET /v1/scrape/{id}`. |
| `costUsd` | `number` | What the call cost, in dollars. |
| `creditsUsed` | `number` | The same charge as a whole number, one for each \$0.002. Read `costUsd` instead. |
| `numPages`, `totalPages`, `ocrPages` | `number` | For a PDF: the pages read, the pages in the file, and the pages read from their picture. See [PDFs and documents](https://docs.stophy.dev/scrape/pdfs-and-documents.md). |
| `error` | `string` | Set when the page answered with a status of 400 or more, such as `The page answered with status 403.` |
| `keywords`, `robots`, `publishedTime`, `modifiedTime`, `articleSection`, `articleTag` | `string` or `array of string` | From the page's `keywords`, `robots` and `article:*` tags. |
| `ogTitle`, `ogDescription`, `ogUrl`, `ogLocale`, `ogLocaleAlternate`, `ogSiteName`, `ogVideo`, `ogAudio`, `ogDeterminer` | `string` or `array of string` | From the page's Open Graph tags. |
| `dcDate`, `dcDateCreated`, `dcDescription`, `dcSubject`, `dcType`, `dcTermsCreated`, `dcTermsKeywords`, `dcTermsSubject`, `dcTermsType`, `dcTermsAudience` | `string` or `array of string` | From the page's Dublin Core tags. |

Every other meta tag on the page also comes back under its own name, such as `twitter:card` or `viewport`. A tag that appears several times comes back as an array of strings.

## Limits and errors

* `metadata` is always an object. A page with no meta tags still has `sourceURL`, `url`, `statusCode`, `contentType` and `cacheState`.
* A YouTube link has no meta tags to read. Its `title`, `description` and `ogImage` come from the video. See [YouTube](https://docs.stophy.dev/scrape/youtube.md).
* A page that answers with a 404 or 410 status comes back with that `statusCode` and an `error`, and costs nothing. See [Timeouts and errors](https://docs.stophy.dev/scrape/timeouts-and-errors.md).

## Related

* [Scrape overview](https://docs.stophy.dev/scrape/overview) lists every format and option.
* [Crawl page content](https://docs.stophy.dev/crawl/page-content.md) shows the same object on every crawled page.
* [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md) explains `cacheState` and `cachedAt`.
* [Markdown](https://docs.stophy.dev/scrape/markdown.md) returns the page text next to this object.


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