Response format

The data lookup endpoints, Search a data source and 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. 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:

{
  "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.
`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.

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:

{
  "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. Without a key, it reports how much of the anonymous allowance is left. See 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.

Exports and SQL

Downloads and SQL queries return tables rather than this envelope. See Export datasets and Query with SQL.

Get started

Data

Working with data

Account

The envelope

The result

Stale results

Usage

Errors

Exports and SQL

​The envelope

​The result

​Stale results

​Usage

​Errors

​Exports and SQL

The envelope

The result

Stale results

Usage

Errors

Exports and SQL