LinkVisits

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/esyurl-fyi/json-schema/esyurl-fyi-link-visits-schema.json",
  "title": "LinkVisits",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/esyurl-fyi-openapi.json#/components/schemas/LinkVisits",
  "type": "object",
  "required": [
    "linkId",
    "slug",
    "visitCount",
    "days",
    "totals",
    "daily",
    "recent"
  ],
  "properties": {
    "linkId": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "visitCount": {
      "type": "integer",
      "description": "Lifetime"
    },
    "lastVisitedAt": {
      "type": "string",
      "format": "date-time"
    },
    "days": {
      "type": "integer"
    },
    "totals": {
      "$ref": "#/$defs/VisitCounts",
      "description": "Over the `days` window"
    },
    "daily": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DailyVisits"
      },
      "description": "One per UTC day, oldest first, zero-filled"
    },
    "recent": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/VisitEvent"
      },
      "description": "Newest first; events are kept 90 days"
    },
    "byItem": {
      "type": "object",
      "description": "Link pages: human clicks in the window by button",
      "properties": {
        "clicks": {
          "type": "integer"
        },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "itemId": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "current": {
                "type": "boolean"
              },
              "clicks": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "byRule": {
      "type": "object",
      "description": "Human visits in the window by deciding rule",
      "properties": {
        "fallback": {
          "type": "integer",
          "description": "Went to the link's targetUrl"
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "ruleId",
              "current",
              "visits"
            ],
            "properties": {
              "ruleId": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "current": {
                "type": "boolean",
                "description": "false: no longer on the link, but has visits in the window"
              },
              "visits": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  },
  "$defs": {
    "DailyVisits": {
      "allOf": [
        {
          "$ref": "#/$defs/VisitCounts"
        },
        {
          "type": "object",
          "required": [
            "date"
          ],
          "properties": {
            "date": {
              "type": "string",
              "format": "date"
            },
            "byRule": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              },
              "description": "Human visits per rule id; only on days a rule matched (link visits only)"
            },
            "clicks": {
              "type": "object",
              "additionalProperties": {
                "type": "integer"
              },
              "description": "Human clicks per link page item id; only on days with clicks (link visits only)"
            }
          }
        }
      ]
    },
    "VisitCounts": {
      "type": "object",
      "required": [
        "visits",
        "qr",
        "direct",
        "bot"
      ],
      "properties": {
        "visits": {
          "type": "integer",
          "description": "Human visits: qr + direct"
        },
        "qr": {
          "type": "integer"
        },
        "direct": {
          "type": "integer"
        },
        "bot": {
          "type": "integer",
          "description": "Link-preview fetchers and crawlers; not part of visits"
        }
      }
    },
    "VisitEvent": {
      "type": "object",
      "required": [
        "at",
        "source"
      ],
      "properties": {
        "at": {
          "type": "string",
          "format": "date-time"
        },
        "source": {
          "type": "string",
          "enum": [
            "qr",
            "direct",
            "bot"
          ]
        },
        "referrerHost": {
          "type": "string"
        },
        "userAgent": {
          "type": "string",
          "maxLength": 256
        },
        "country": {
          "type": "string",
          "description": "ISO 3166-1 alpha-2, when the edge provides it"
        },
        "ruleId": {
          "type": "string",
          "description": "The redirect rule that picked the destination; absent when targetUrl was used"
        }
      }
    }
  }
}