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

# Response format

> The JSON shape every data source returns.

The data lookup endpoints, [Search a data source](/api-reference/data-sources/search-a-data-source) and [Fetch an article by pasting its URL](/api-reference/data-sources/fetch-an-article-by-pasting-its-url), return this envelope whichever source you query, and so does the search tool in the connector. See [Connect an AI tool](/ai-tools). Every source returns data in the same format, so the code you write to read it works for all of them: `data.body` is text for a model, and `data.metadata` holds the structured fields for code.

Here is the result for the paper "Attention Is All You Need" from the `arxiv` source, with the `body` shortened:

```json theme={null}
{
  "status": "success",
  "account_state": "authenticated",
  "data": {
    "id": "arxiv_1706.03762",
    "title": "Attention Is All You Need",
    "body": "Authors: Ashish Vaswani, Noam Shazeer, Niki Parmar, Jakob Uszkoreit, Llion Jones … (+3 more)\nPublished: 2017-06-12\nCategories: cs.CL, cs.LG\n\nThe dominant sequence transduction models are based on complex recurrent or convolutional neural networks...",
    "source": "arxiv",
    "language": "en",
    "last_updated": "2023-08-02T00:41:18Z",
    "entities": ["Ashish Vaswani", "Noam Shazeer", "Niki Parmar", "Jakob Uszkoreit", "Llion Jones", "Aidan N. Gomez", "Lukasz Kaiser", "Illia Polosukhin"],
    "metadata": {
      "arxiv_id": "1706.03762",
      "abs_url": "http://arxiv.org/abs/1706.03762v7",
      "pdf_url": null,
      "published": "2017-06-12T17:57:34Z",
      "authors": ["Ashish Vaswani", "Noam Shazeer", "Niki Parmar", "Jakob Uszkoreit", "Llion Jones", "Aidan N. Gomez", "Lukasz Kaiser", "Illia Polosukhin"],
      "categories": ["cs.CL", "cs.LG"]
    }
  },
  "usage": {
    "credits_total": 29,
    "credits_remaining": 24.11,
    "credits_used": 4.89,
    "request_cost": 0.005
  }
}
```

## The envelope

Every response has these top-level fields.

| Field | What it holds |
| - | - |
| `status` | `success` or `error`. |
| `account_state` | `authenticated` when your API key was accepted, otherwise `anonymous`. |
| `data` | The result. On an error, a message and a code instead. See [Troubleshooting](/api-reference/errors). |
| `usage` | What the request cost and what you have left. |

## The result

`data` has the same fields for every source. Only the contents of `metadata` change. These are the fields worth knowing about:

| Field | What it holds |
| - | - |
| `body` | The record as text: one `Key: value` per line. It is written to be read by people and by models. You can pass it to a model without changing it. |
| `metadata` | Structured fields specific to the source, such as a paper's categories and PDF link, or a filing's date. Read these in code rather than parsing `body`. |
| `last_updated` | When the record last changed at its source. |
| `entities` | Names and terms found in the record. |
| `stale` | Present only when the result came from Dataville's stored copy. |

The full schema, including `id`, `title`, `source`, and `language`, is on [Search a data source](/api-reference/data-sources/search-a-data-source).

## Stale results

When a source is unavailable and Dataville has a stored copy of the record, the response is still `success` and carries a `stale` object inside `data`:

```json theme={null}
{
  "stale": {
    "message": "arxiv is unavailable right now, so this result comes from our stored copy and may be out of date or incomplete. Nothing is wrong with your query.",
    "cached_at": "2026-08-24T09:12:00Z"
  }
}
```

The answer is real but may be out of date. If you need current data, check for `stale` and retry later.

## Usage

With an API key, `usage` reports what the request cost and your remaining credit. See [Plans and credits](/plans-and-credits). Without a key, it reports how much of the anonymous allowance is left. See [Usage limits](/api-reference/usage-limits).

The same numbers are in the response headers, so you can read them without parsing the body.

## Errors

Errors use the same envelope with `status` set to `error`. `data.error` is a message you can show to a user, and `data.code` is a stable string to branch on. See [Troubleshooting](/api-reference/errors).

## Exports and SQL

Downloads and SQL queries return tables rather than this envelope. See [Export datasets](/export-datasets) and [Query with SQL](/query-with-sql).


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