POST /api/runs/:runId/events

Summary

Appends a new event to an existing run identified by runId.

Intent

Allows clients to record discrete events (such as status updates, log messages, or lifecycle milestones) against a specific run, enabling an audit trail or real-time progress tracking for that run.

Parameters

Name	Type	Required	Description
runId	string	Yes	The unique identifier of the run to which the event will be appended. Provided as a URL path segment.
type	string	Yes	A string categorizing the event (e.g. ‘info’, ‘error’, ‘warning’). Must be present in the request body.
message	string	Yes	A human-readable description of the event. Must be present in the request body.
metadata	object	No	An optional free-form key-value map providing additional context about the event.

Request example

curl -X POST https://maps.google.com/api/runs/run_abc123/events \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "info",
    "message": "Pipeline step completed successfully.",
    "metadata": {
      "step": "extraction",
      "durationMs": 342
    }
  }'

Response example

{
  "ok": true
}

Error cases

• 400 — Either ‘type’ or ‘message’ is missing from the request body.
• 404 — No run exists for the provided runId.

Gotchas

• Both ‘type’ and ‘message’ are required in the request body — omitting either returns a 400 even if the other field is present.
• The runId must correspond to an existing run in the store; there is no auto-creation of runs.
• The ‘metadata’ field accepts any arbitrary key-value pairs but must be a JSON object (not an array or primitive) if provided.
• A successful response returns HTTP 201, not 200 — clients checking for 200 will incorrectly treat success as a failure.
• Each event is assigned a server-generated UUID; clients cannot supply their own event ID.