Stream results
Introduced in 2025.12

The Query API can stream values as events over HTTP. This allows clients to process data incrementally as it arrives, improving memory efficiency and enabling applications to handle larger datasets.

You enable streaming by tweaking the Accept header:

For Plain JSON, application/jsonl.
For Typed JSON, add the suffix +jsonl. For example, application/vnd.neo4j.query.v1.1+jsonl.

For clarity, JSON objects in this page are formatted with line breaks. In reality, each event is represented as a single line.

Object structure

Each response consists of a sequence of events, each represented as a JSON object with the following structure:

{
    "$event": "Header | Record | Summary | Error",
    "_body": { /* event-specific payload */ }
}

$event — The type of event. Possible values are: Header, Record, Summary, Error.
_body — The event-specific body. The structure of this field varies depending on the event type.

Clients must consume events in the order they are received.

The header Transfer-Encoding: chunked is used in HTTP/1.1 requests for transferring data in chunks. HTTP/2 connections don’t need this header.

Message Sequencing

The Query API streaming response consists of a sequence of JSON events delivered in JSON Lines format.

Events are emitted in the following order:

Header — Sent first. Defines the result structure and field names.
Record — Zero or more events, each containing a single row of result data.
Summary — Sent once, after all records are streamed. Contains execution metadata.
Error — May appear at any point in the stream if an error occurs. When an Error event is emitted, no further events are sent.

The stream is complete once a Summary or Error event is received.

Successful Example

Header
Record
Record
Record
Summary

{"$event":"Header","_body":{"fields":["name","age"]}}
{"$event":"Record","_body": ["Alice",32]}
{"$event":"Record","_body": ["Bob",29]}
{"$event":"Summary","_body":{"bookmarks":["FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"]}}

Failure Example

In case of failure, the stream is terminated immediately after the Error event.

Header
Error

{"$event":"Header","_body":{"fields":["name","age"]}}
{"$event":"Error","_body":[{"code":"Neo.ClientError.Statement.SyntaxError","message":"Invalid input 'RETURN'"}]}

Event Types

Each event type has a distinct payload format.

`Header` Event

The Header event is sent first in the stream. It provides metadata about the query result, such as the names and types of the returned fields. Information about the created transaction might also be present.

{
  "$event": "Header",
  "_body": {
    "fields": ["name", "age"]
  }
}

fields (optional) — An array of column names included in each subsequent Record event. This is not present when creating transactions without running a query.

`Record` Event

The Record event carries a single row of query data. One Record event is emitted for each result row.

{
  "$event": "Record",
  "_body": ["Antonio", 39]
}

{
  "$event": "Record",
  "_body": [{ "$type": "String", "_value": "Antonio" }, { "$type": "Integer",  "_value": "39" }]
}

_body — An array containing the field values for the record. The order matches the fields array defined in the Header event. The format depends on whether Plain JSON or Typed JSON is used.

Since data arrives incrementally, the client should not assume that all Record events are available before processing.

`Summary` Event

The Summary event marks the end of the stream and provides metadata about the query execution.

{
  "$event": "Summary",
  "_body": {
    "bookmarks": ["FB:kcwQ/wTfJf8rS1WY+GiIKXsCXgmQ"],
    "transaction": {
      "id": "lyU",
      "expires": "2024-10-22T15:48:29Z"
    },
    "notifications": [ /* notifications structure */ ],"counters": { /* counters structure */},
    "queryPlan": { /* query plan structure */ },
    "profiledQueryPlan": { /* profiled query plan structure */ }
  }
}

bookmarks (optional) — A list of database bookmarks. Only present when the response represents a committed transaction.
transaction (optional) — An object with the transaction information.
notifications (optional) — Warnings or informational messages generated during query execution. See Server notifications.
counters (optional) — Statistics about the changes performed by the query. See Retrieve query counters.
queryPlan (optional) — The logical query plan. See Profile queries.
profiledQueryPlan (optional) — Detailed execution metrics, if the query was run with profiling enabled. See Profile queries.

`Error` Event

The Error event indicates that an error occurred during query execution or streaming.

{
  "$event": "Error",
  "_body": [{
    "code": "Neo.ClientError.Statement.SyntaxError"
    "message": "Invalid input 'RETURN'"
  }]
}

code — The Neo4j error code.
message — A human-readable error description.

Stream resultsIntroduced in 2025.12