Documentation
DocumentationDiscussions
Documentation

Ingestion with HTTP

Events can be sent directly to the Seq API by posting JSON via HTTP/S

In some situations it may be desirable to send events to Seq without using a telemetry library like Serilog or OpenTelemetry. In that case, batches of events can be sent in newline-delimited JSON format directly to Seq's HTTP API.

Compact JSON format

Events are POSTed to the /ingest/clef endpoint:

POST https://localhost:5341/ingest/clef

The /ingest/clef endpoint accepts compact JSON format (CLEF) payloads.

If an API key is required, it can be specified as ?apiKey= in the URL, or sent in the X-Seq-ApiKey HTTP header.

To identify the payload as compact log event format, specify the value application/vnd.serilog.clef in the ContentType header. Single events may be sent with the application/json content type.

The CLEF format

Batches of events in this format are newline-separated JSON documents:

{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {User}","User":"alice"}
{"@t":"2016-06-07T04:10:00.3457981Z","@mt":"Hello, {User}","User":"bob"}

Each event is a JSON object with event data at the top level. Any JSON property on the payload object is assumed to be a regular property of the event, apart from the reified properties below.

Reified properties

The format defines a handful of properties that have special meaning.

PropertyNameDescriptionRequired?
@tTimestampAn ISO 8601 timestampYes
@mMessageA fully-rendered message describing the event
@mtMessage templateAlternative to @m; specifies a message template over the event's properties that provides for rendering into a textual description of the event
@lLevelAn implementation-specific level identifier; Seq requires a string value if presentAbsence implies "informational"
@xExceptionA language-dependent error representation potentially including backtrace; Seq requires a string value, if present
@iEvent idAn implementation-specific event id; Seq uses this field for the event type, and accepts either numeric or hexadecimal string values.
@rRenderingsIf @mt includes tokens with programming-language-specific formatting, an array of pre-rendered values for each such tokenMay be omitted; if present, the count of renderings must match the count of formatted tokens exactly
@trTrace idAn identifier that groups all spans and logs that are in the same traceYes, if the event is a span
@spSpan idUnique identifier of a spanYes, if the event is a span
@psParent idThe span id of this span's parent; absence indicates that this is the root span of a trace
@stStartThe start ISO 8601 timestamp of this spanYes, if the event is a span
@scInstrumentation scopeDescribes the application-local component responsible for the event
@raResource attributesDescribes the system-level component responsible for the event
@skSpan kindDescribes the relationship of the span to others in the trace: Client, Server, Internal, Producer, or Consumer

The @ sigil may be escaped at the start of a user property name by doubling, e.g. @@name denotes a property called @name.

Except for @mt, property names with two characters, such as @tr, are later extensions to the original, minimal CLEF specification that may not be recognized by other systems.

Batch format

When events are batched into a single payload, a newline-delimited stream of JSON documents is required. Either \n or \r\n delimiters may be used. Batches of newline-separated compact JSON events can use the (unofficial) MIME type application/vnd.serilog.clef.

Status codes and response format

The POST request will return one of the following status codes:

Status codeMeaning
201 CreatedThe events were ingested successfully
400 Bad RequestThe request was malformed; sometimes this indicates incorrect payload formatting, or more frequently, an included event exceeds the configured maximum event size
401 UnauthorizedAuthorization is required; this status code may be returned if an API key is missing or invalid
403 ForbiddenThe provided credentials don't have ingestion permission
413 Request Entity Too LargeThe payload itself exceeds the configured maximum size
500 Internal Server ErrorAn internal error prevented the events from being ingested; check Seq's diagnostic log for more information
503 Service UnavailableThe Seq server is starting up and can't currently service the request, or, free storage space has fallen below the minimum required threshold; this status code may also be returned by HTTP proxies and other network infrastructure when Seq is unreachable

If the status code indicates success, the response will be of the form:

{"MinimumLevelAccepted": null}

The MinimumLevelAccepted value will be null if no level filter is applied, and one of the Serilog level values Verbose, Debug, Information, Warning, Error and Fatal if filtering is applied. The client may use these values to pre-filter events and therefore reduce network bandwidth utilization.

If the status code indicates failure, the response will be of the form:

{"Error": "This is an error message"}

📘

Classic format

Versions of Seq prior to 3.3 only accept the classic payload format, which takes the form of a single JSON document POSTed to /api/events/raw. See the earlier versions of this documentation for details.