{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/devtune/json-schema/devtune-timeline-event-schema.json",
  "title": "TimelineEvent",
  "x-generated": "2026-11-16",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/devtune-openapi.json#/components/schemas/TimelineEvent",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "source": {
      "type": "string",
      "enum": [
        "external",
        "team",
        "deterministic",
        "detected",
        "measured_action"
      ],
      "description": "Where the event comes from. external: a sourced fact DevTune published, such as a platform model change or outage. team: a fact the DevTune team published. deterministic: a change recorded in the project, such as prompts added. detected: a change DevTune found in citations or AI Traffic. measured_action: a step in measuring a shipped action."
    },
    "kind": {
      "type": "string",
      "enum": [
        "change_detected",
        "change_claimed",
        "measurement_opened",
        "outcome_measured",
        "prompts_added",
        "prompts_edited",
        "prompts_paused",
        "prompts_resumed",
        "prompts_deleted",
        "prompts_restored",
        "topic_deleted",
        "tracked_urls_changed",
        "platform_model_change",
        "platform_outage",
        "data_collection_gap",
        "search_algorithm_update",
        "citation_share_change",
        "ai_traffic_change",
        "devtune_methodology_change"
      ],
      "description": "What happened. Measured actions use change_detected, change_claimed, measurement_opened or outcome_measured. Detected citation-share changes use citation_share_change and detected AI Traffic changes use ai_traffic_change. Platform, data-collection and DevTune changes, and prompt or topic changes, have their own kinds."
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "description": "When it happened. A detected change for this project is placed at 03:00 UTC on the day it was first seen."
    },
    "endedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When a fact DevTune published that spans time, such as an outage, ended. Null when the fact has no end time, and on every project event."
    },
    "platformKeys": {
      "description": "The AI platforms the event concerns. Null when it is not about particular platforms, and on AI Traffic changes; read trafficChange.platform for those.",
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "titleKey": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null. Titles come from evidence."
    },
    "evidence": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "measuredAction": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "actionId": {
              "type": "string",
              "format": "uuid"
            },
            "actionTitle": {
              "type": "string"
            },
            "agentPicks": {
              "type": "object",
              "additionalProperties": true,
              "description": "Structured Agent Picks Action rationale for localized titles. Only present with agent_picks enabled; reason Actions include the reason and all covered cells."
            },
            "interventionId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The measured action’s before/after window."
            },
            "changeEventId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "The content change behind the event. Null when a result has no linked content change. Absent on a measurement opening."
            },
            "url": {
              "type": [
                "string",
                "null"
              ],
              "description": "The page the action changed. An empty string when the action names no page."
            },
            "result": {
              "type": "string",
              "enum": [
                "improved",
                "mixed",
                "no_clear_change",
                "declined",
                "still_measuring",
                "unmeasured"
              ],
              "description": "What the before/after window shows. It records what moved, not what caused it."
            },
            "measurementOpenedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the before/after window opened. Absent on a change event."
            },
            "windowClosedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the window closed. Only on a result event. Null when no window close was recorded."
            },
            "method": {
              "type": "string",
              "enum": [
                "v1",
                "v2"
              ],
              "description": "Method used for an outcome_measured result."
            },
            "agentPicksMethod": {
              "type": "string",
              "enum": [
                "v1",
                "v2"
              ],
              "description": "On an Agent Picks outcome_measured event, the method its stored result was decided by: v2 compares the re-test with its baseline by the 90% interval on their difference, v1 by 95% ranges. A result stored without one is v1."
            }
          },
          "required": [
            "interventionId",
            "url"
          ],
          "description": "The measured action behind the event. Changes and results carry changeEventId; openings and results carry measurementOpenedAt. Only results carry result and windowClosedAt, and a result event is placed when Results measured it."
        },
        "detectedEvidence": {
          "description": "A detected citation-share change: across every tracked project, or for this project. Only on detected citation-share events.",
          "anyOf": [
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "platform": {
                  "type": "string"
                },
                "domain": {
                  "type": "string",
                  "description": "The cited domain whose share changed."
                },
                "direction": {
                  "type": "string",
                  "enum": [
                    "up",
                    "down"
                  ],
                  "description": "Whether the share rose or fell."
                },
                "currentShare": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "The domain's share of the platform's citations in the observation period, from 0 to 1."
                },
                "baselineShare": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "The same share in the baseline period, from 0 to 1."
                },
                "absoluteChange": {
                  "type": "number",
                  "description": "currentShare minus baselineShare, on the same 0 to 1 scale."
                },
                "relativeChange": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "The change relative to baselineShare. Null when baselineShare is 0."
                },
                "observationStart": {
                  "type": "string",
                  "format": "date",
                  "description": "First day of the observation period."
                },
                "observationEnd": {
                  "type": "string",
                  "format": "date",
                  "description": "Last day of the observation period."
                },
                "projectCount": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Tracked projects across DevTune where the change was seen."
                },
                "projectFraction": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "projectCount as a share of the projects that could be compared on this platform, from 0 to 1."
                }
              },
              "required": [
                "platform",
                "domain",
                "direction",
                "currentShare",
                "baselineShare",
                "absoluteChange",
                "relativeChange",
                "observationStart",
                "observationEnd",
                "projectCount",
                "projectFraction"
              ]
            },
            {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "platform": {
                  "type": "string"
                },
                "domain": {
                  "type": "string",
                  "description": "The cited domain whose share changed."
                },
                "direction": {
                  "type": "string",
                  "enum": [
                    "up",
                    "down"
                  ],
                  "description": "Whether the share rose or fell."
                },
                "currentShare": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "The domain's share of the platform's citations in the observation period, from 0 to 1."
                },
                "baselineShare": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1,
                  "description": "The same share in the baseline period, from 0 to 1."
                },
                "absoluteChange": {
                  "type": "number",
                  "description": "currentShare minus baselineShare, on the same 0 to 1 scale."
                },
                "relativeChange": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "The change relative to baselineShare. Null when baselineShare is 0."
                },
                "observationStart": {
                  "type": "string",
                  "format": "date",
                  "description": "First day of the observation period."
                },
                "observationEnd": {
                  "type": "string",
                  "format": "date",
                  "description": "Last day of the observation period."
                },
                "scope": {
                  "type": "string",
                  "enum": [
                    "project"
                  ]
                },
                "domainRole": {
                  "type": "string",
                  "enum": [
                    "own",
                    "competitor",
                    "other"
                  ],
                  "description": "own for a primary brand domain, competitor for a tracked competitor’s, other for any other source."
                },
                "brandName": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The brand the domain belongs to. Null when domainRole is other, or when the brand has since been deleted."
                },
                "incidentId": {
                  "type": "string",
                  "format": "uuid"
                },
                "baselineStart": {
                  "type": "string",
                  "format": "date",
                  "description": "First day of the baseline period."
                },
                "baselineEnd": {
                  "type": "string",
                  "format": "date",
                  "description": "Last day of the baseline period."
                },
                "cohortPromptCount": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Prompts compared across both periods."
                },
                "activePromptCount": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Prompts active in the observation period."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "active",
                    "resolved"
                  ],
                  "description": "active while the change holds, resolved once it no longer does."
                },
                "resolvedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time",
                  "description": "When the change resolved. Null while active."
                }
              },
              "required": [
                "platform",
                "domain",
                "direction",
                "currentShare",
                "baselineShare",
                "absoluteChange",
                "relativeChange",
                "observationStart",
                "observationEnd",
                "scope",
                "domainRole",
                "brandName",
                "incidentId",
                "baselineStart",
                "baselineEnd",
                "cohortPromptCount",
                "activePromptCount",
                "status",
                "resolvedAt"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "trafficChange": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "incidentId": {
              "type": "string",
              "format": "uuid"
            },
            "platform": {
              "type": "string",
              "description": "AI Traffic provider key, for example openai or anthropic."
            },
            "classGroup": {
              "type": "string",
              "enum": [
                "answer_fetches",
                "crawls"
              ],
              "description": "answer_fetches for answer fetchers, crawls for training and index crawlers."
            },
            "direction": {
              "type": "string",
              "enum": [
                "up",
                "down"
              ],
              "description": "Whether requests rose or fell."
            },
            "observedEvents": {
              "type": "integer",
              "minimum": 0,
              "description": "Requests in the observation period."
            },
            "baselineEvents": {
              "type": "integer",
              "minimum": 0,
              "description": "Requests in the baseline period."
            },
            "expectedEvents": {
              "type": "integer",
              "minimum": 0,
              "description": "baselineEvents scaled to the observation period’s length."
            },
            "relativeChange": {
              "type": [
                "number",
                "null"
              ],
              "description": "observedEvents minus expectedEvents, divided by expectedEvents. Null when the baseline has no events."
            },
            "observationStart": {
              "type": "string",
              "format": "date",
              "description": "First day of the observation period."
            },
            "observationEnd": {
              "type": "string",
              "format": "date",
              "description": "Last day of the observation period."
            },
            "baselineStart": {
              "type": "string",
              "format": "date",
              "description": "First day of the baseline period."
            },
            "baselineEnd": {
              "type": "string",
              "format": "date",
              "description": "Last day of the baseline period."
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "resolved"
              ],
              "description": "active while the change holds, resolved once it no longer does."
            },
            "resolvedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the change resolved. Null while active."
            }
          },
          "required": [
            "incidentId",
            "platform",
            "classGroup",
            "direction",
            "observedEvents",
            "baselineEvents",
            "expectedEvents",
            "relativeChange",
            "observationStart",
            "observationEnd",
            "baselineStart",
            "baselineEnd",
            "status",
            "resolvedAt"
          ],
          "description": "Detected AI Traffic change for one provider and class group. answer_fetches counts answer fetchers; crawls counts training and index crawlers. expectedEvents is the baseline scaled to the observation window length; relativeChange is null when the baseline has no events. Only high-confidence changes measured with complete sensor coverage surface, and only where AI Traffic is available."
        }
      },
      "description": "What the event is based on. Detected AI Traffic changes (ai_traffic_change) return trafficChange. Detected facts return global aggregate or project incident detectedEvidence. Project evidence includes domainRole (own, competitor or other), brandName (null for other, or once the brand is deleted), scope, incidentId, baseline dates, prompt counts, status and resolvedAt; only global evidence includes projectCount and projectFraction. External facts return title, description, and sourceUrl. Prompt additions include promptCount, topic, and requestedBy. Prompt edits (prompts_edited) and prompts switched off (prompts_paused) or on (prompts_resumed) return the same fields, one event per kind per day, counting each prompt once; edits and switches made before DevTune recorded them are not returned. Deletions also include jobId and activeSlotsFreed; restores include jobId and topicRestored. Prompt names are not returned. Tracked-URL changes (tracked_urls_changed, one per day) include changeCount, brands (up to five affected brand names), brandCount, requestedBy and requestedByCredential (the API key reference and name, or MCP connection reference, when every change has the same credential); they apply to citations collected from that day on, and earlier citations keep the labels they were recorded with."
    }
  },
  "required": [
    "id",
    "source",
    "kind",
    "occurredAt",
    "endedAt",
    "platformKeys",
    "titleKey",
    "evidence"
  ]
}