> For the complete documentation index, see [llms.txt](https://developer.aiodds.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.aiodds.com/help-center/snapshot/snapshot-v2-user-guide.md).

# Snapshot v2 User Guide

## Client integration guidelines

#### 1. Use a streaming HTTP client

Do <mark style="color:$danger;">**not**</mark> call APIs that wait for the full body (e.g. `response.json()` / `read().decode()` on the entire stream) unless the dataset is known to be small and you accept high memory use.

Prefer clients that expose an incremental byte/text stream:

* Python: `httpx` / `aiohttp` / `requests` with `stream=True`
* Node.js: `fetch` body as `ReadableStream`, or `got` / `undici` streaming
* Go: `http.Response.Body` + `bufio.Scanner`
* Java: OkHttp / HttpClient with streaming body readers

#### 2. Read line by line

Recommended consumption loop:

1. Open the request and keep the connection open
2. Read the response body as a text/byte stream
3. Split on `\n` (handle partial lines across TCP chunks — use a buffer)
4. For each complete non-empty line:
   * `JSON.parse` / `json.loads` / equivalent
   * Validate `code == 0` (as needed)
   * Process `data.list` for that batch
5. When the stream ends (EOF), treat the snapshot as complete

#### 3. Buffer incomplete lines

Network chunks rarely align with newline boundaries. Always maintain a leftover buffer:

```
buffer += chunk
while "\n" in buffer:
    line, buffer = buffer.split("\n", 1)
    if line.strip():
        handle(json.loads(line))
# after EOF: if buffer has leftover text, parse it if non-empty
```

#### 4. Process incrementally

For each batch line, process or persist `data.list` immediately (write to DB, push to queue, merge into local cache, etc.). Avoid accumulating every batch into one giant in-memory list unless required.

#### 5. Timeouts and connection settings

Streaming responses can run longer than typical REST calls. Configure:

* A **connect** timeout (short)
* A **read** timeout that allows idle gaps between batches, or disable read timeout for the stream
* Keep-alive / no premature client-side cancellation

#### 6. Error handling

| Situation                         | Suggested handling                                   |
| --------------------------------- | ---------------------------------------------------- |
| HTTP 4xx/5xx before/during stream | Abort; inspect status and error body if present      |
| Malformed JSON on a line          | Log and skip, or abort — depending on your SLOs      |
| Stream closes mid-transfer        | Treat snapshot as incomplete; retry the full request |
| Empty stream (EOF with no lines)  | Valid empty snapshot for the given filters           |

#### 7. Idempotent full refresh

This endpoint is a **full snapshot pull**, not a delta/diff feed. Typical pattern:

1. Call snapshot
2. Consume all JSONL lines to completion
3. Replace or merge into your local store
4. Re-poll on your schedule (respect rate limits)

## Checklist for integrators

* Request uses streaming / chunked body reading
* Parser splits on `\n` and handles partial lines
* Each line is parsed as an independent JSON object
* Batches are processed as they arrive
* EOF is treated as “snapshot complete”
* Timeouts allow a long-lived stream
* Incomplete streams are retried as a full refresh
* &#x20;`Content-Type: application/jsonl` is expected (not `application/json`)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.aiodds.com/help-center/snapshot/snapshot-v2-user-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.