POST /v1/logs — Batch Ingest Structured Log Entries

POST

logs

curl -X POST https://api.peeng.dev/v1/logs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 5b3f9e2a-6c1d-4e8a-9f2b-1a3c5d7e9f0b" \
  -d '{
    "logs": [
      {
        "level": "error",
        "message": "Payment webhook failed",
        "environment": "production",
        "service": "billing",
        "statusCode": 500,
        "stackTrace": "Error: timeout\n    at processPayment (billing.js:42)",
        "requestId": "req_8f2a1c",
        "metadata": { "orderId": "order_789", "provider": "stripe" }
      },
      {
        "level": "info",
        "message": "Order placed",
        "environment": "production",
        "service": "checkout",
        "statusCode": 200,
        "userId": "user_456"
      }
    ]
  }'

{
  "accepted": 2
}

POST /v1/logs is the single ingestion endpoint for the Peeng API — it accepts a batch of 1 to 500 structured log entries in one request and is the same endpoint every Peeng SDK method calls under the hood. You can use it directly with any HTTP client if you prefer to stay dependency-free.

Headers

string

required

Your project’s API key. See Authentication for how to obtain and manage keys.

string

A key unique to this batch. Safe to reuse on retries for up to 24 hours — Peeng returns the original response without writing duplicate entries. See Idempotency.

string

required

Must be application/json.

Request Body

array

required

An array of 1 to 500 log entry objects. Every entry in the array is validated; if any entry fails validation the entire request is rejected with a 400 and nothing is written.

Show Log entry fields

string

required

Severity level of the log entry. Must be one of debug, info, warn, error, or fatal.

string

required

The human-readable log message describing the event.

string

required

The environment that emitted this log — for example production, staging, or development. Use any string you apply consistently across your services so you can filter by environment in the dashboard.

integer

required

A value between 100 and 599 that models the outcome of the operation this log describes — 200 for a routine success, 500 for an unhandled error, and so on. This is not tied to the HTTP status code of the ingestion request itself.

string

The name of the service or process that emitted this log, e.g. checkout-api. Use this to group and filter logs by service in the dashboard.

object

Any JSON-serializable object containing extra structured context for this log entry — for example request parameters, feature flags, or business identifiers.

string

The full stack trace text associated with an error. Providing this field enables the Explain with AI feature in the Peeng dashboard, which summarises the root cause and suggests a fix.

string

The hostname or instance identifier of the machine that emitted the log. Useful for pinpointing issues on a specific node in a distributed system.

string

A request or trace ID that correlates this log entry with the inbound request that triggered it. Use this to reconstruct a request’s full journey across services.

string

The identifier of the end user this log pertains to, if applicable. Lets you search and filter logs by user in the dashboard.

string

The time the event occurred, in ISO 8601 format (e.g. 2025-01-15T10:30:00.000Z). If you omit this field, Peeng stamps the entry with the time the request was received. Supply an explicit timestamp when you buffer and flush entries asynchronously.

curl -X POST https://api.peeng.dev/v1/logs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 5b3f9e2a-6c1d-4e8a-9f2b-1a3c5d7e9f0b" \
  -d '{
    "logs": [
      {
        "level": "error",
        "message": "Payment webhook failed",
        "environment": "production",
        "service": "billing",
        "statusCode": 500,
        "stackTrace": "Error: timeout\n    at processPayment (billing.js:42)",
        "requestId": "req_8f2a1c",
        "metadata": { "orderId": "order_789", "provider": "stripe" }
      },
      {
        "level": "info",
        "message": "Order placed",
        "environment": "production",
        "service": "checkout",
        "statusCode": 200,
        "userId": "user_456"
      }
    ]
  }'

{
  "accepted": 2
}

Response Fields

A 202 response body contains a single field confirming how many entries were written.

integer

The number of log entries persisted from this request. A 202 response with accepted equal to the length of the logs array confirms that every entry in the batch was written successfully. There is no partial-success shape — a request either succeeds entirely or fails validation entirely, so accepted will always match the number of entries you submitted on a 202.

Response Codes

Code	Meaning
`202`	Accepted — all entries in the batch were persisted.
`400`	Validation failed on one or more entries.
`401`	Missing or invalid API key.
`402`	Monthly ingestion limit reached for your plan.
`409`	Same `Idempotency-Key` is already being processed.
`429`	Rate limited.

See Errors for the full response envelope shape and retry guidance.

curl -X POST https://api.peeng.dev/v1/logs \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 5b3f9e2a-6c1d-4e8a-9f2b-1a3c5d7e9f0b" \
  -d '{
    "logs": [
      {
        "level": "error",
        "message": "Payment webhook failed",
        "environment": "production",
        "service": "billing",
        "statusCode": 500,
        "stackTrace": "Error: timeout\n    at processPayment (billing.js:42)",
        "requestId": "req_8f2a1c",
        "metadata": { "orderId": "order_789", "provider": "stripe" }
      },
      {
        "level": "info",
        "message": "Order placed",
        "environment": "production",
        "service": "checkout",
        "statusCode": 200,
        "userId": "user_456"
      }
    ]
  }'

{
  "accepted": 2
}

Overview

Logs

POST /v1/logs — Batch Ingest Structured Log Entries

Headers

Request Body

Response Fields

Response Codes

​Headers

​Request Body

​Response Fields

​Response Codes

Headers

Request Body

Response Fields

Response Codes