Skip to content

Read pipeline output

POST
/serve

Reads events from an existing pipeline output stream. By default, the endpoint uses long polling (timeout: 5s) and returns as soon as at least one event is available (min_events: 1).

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Pipeline output request.

object
serve_id
required

The output stream identifier returned when the pipeline was launched.

string
Example
query-1
continuation_token

The continuation token from the previous response. Omit this field for the initial request.

string
Example
340ce2j
max_events

The maximum number of events to return.

integer
default: 1024
Example
1024
min_events

The minimum number of events to wait for before returning.

integer
default: 1
Example
1
timeout

The maximum time to spend on the request. Reaching the timeout returns the available events and is not an error. The timeout must not be greater than 10 seconds.

string
default: 5s
Example
200ms
schema

The schema representation to include in the response. Use exact for a representation that matches Tenzir’s type system exactly, and never to omit schema definitions.

string
default: legacy
Allowed values: legacy exact never
Example
exact
Example
{
  "serve_id": "query-1",
  "max_events": 1024,
  "min_events": 1,
  "timeout": "5s",
  "schema": "exact"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Events are available, the timeout was reached, or the pipeline reached a terminal state.

object
next_continuation_token
required

The token to use when reading the next batch. The value is null when the pipeline reached a terminal state.

string
nullable
Example
340ce2j
state
required

The pipeline state at the time of the request.

string
Allowed values: running completed failed
Example
running
schemas

The schemas for the returned events. This field is omitted when the request sets schema to never.

Array<object>
object
schema_id

The unique schema identifier.

string
definition

The schema definition in JSON format.

Example
[
  {
    "schema_id": "c631d301e4b18f4",
    "definition": [
      {
        "name": "tenzir.summarize",
        "kind": "record",
        "type": "tenzir.summarize",
        "attributes": {},
        "path": [],
        "fields": [
          {
            "name": "severity",
            "kind": "string",
            "type": "string",
            "attributes": {},
            "path": [
              0
            ],
            "fields": []
          },
          {
            "name": "pipeline_id",
            "kind": "string",
            "type": "string",
            "attributes": {},
            "path": [
              1
            ],
            "fields": []
          }
        ]
      }
    ]
  }
]
events
required

The returned events.

Array<object>
object
schema_id

The unique schema identifier.

string
data

The event data in JSON format.

object
Example
[
  {
    "schema_id": "c631d301e4b18f4",
    "data": {
      "timestamp": "2023-04-26T12:00:00Z",
      "schema": "zeek.conn",
      "schema_id": "ab2371bas235f1",
      "events": 50
    }
  },
  {
    "schema_id": "c631d301e4b18f4",
    "data": {
      "timestamp": "2023-04-26T12:05:00Z",
      "schema": "suricata.dns",
      "schema_id": "cd4771bas235f1",
      "events": 50
    }
  }
]
Example
{
  "next_continuation_token": "340ce2j",
  "state": "running",
  "schemas": [
    {
      "schema_id": "c631d301e4b18f4",
      "definition": {
        "name": "tenzir.summarize",
        "kind": "record",
        "type": "tenzir.summarize",
        "attributes": {},
        "path": [],
        "fields": []
      }
    }
  ],
  "events": [
    {
      "schema_id": "c631d301e4b18f4",
      "data": {
        "timestamp": "2023-04-26T12:00:00Z",
        "schema": "zeek.conn",
        "events": 50
      }
    }
  ]
}

400

Section titled “400 ”

The request body is invalid.

object
error
required

The error message.

string
Example
Invalid arguments