space.highport.manage.getSiteTraffic

{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "main": {
      "description": "Traffic to one domain the caller owns, over a range: requests and bytes per hour, the busiest paths, and the status mix. Byte figures include a flat per-response header estimate, because the edge's access log records the response body only.",
      "errors": [
        {
          "description": "Not a syntactically valid, non-reserved, public-suffix-safe domain. Distinct from DomainNotFound: the string is not a hostname at all.",
          "name": "InvalidDomain"
        },
        {
          "description": "No such domain, or it is not registered to the calling identity. The two are one answer so the method is not an existence oracle.",
          "name": "DomainNotFound"
        },
        {
          "description": "This deployment has no analytics store configured, so no traffic was ever recorded.",
          "name": "AnalyticsDisabled"
        }
      ],
      "output": {
        "encoding": "application/json",
        "schema": {
          "properties": {
            "buckets": {
              "description": "Hourly buckets, oldest first.",
              "items": {
                "description": "One hour of a domain's traffic.",
                "properties": {
                  "botRequests": {
                    "description": "How many of requests came from a client classified as a crawler, which is a subset of it and not a sibling. There is no byte-level equivalent: the bucket carries no client_class split of bytesBody or bytesBilled. Absent from a deployment that does not report the split, which a reader shows as no answer rather than as no crawlers.",
                    "type": "integer"
                  },
                  "bucket": {
                    "description": "The hour this bucket starts.",
                    "format": "datetime",
                    "type": "string"
                  },
                  "bytesBilled": {
                    "description": "Body bytes plus the per-response header estimate.",
                    "type": "integer"
                  },
                  "bytesBody": {
                    "description": "Response body bytes, as the edge logged them.",
                    "type": "integer"
                  },
                  "requests": {
                    "description": "Responses in the hour.",
                    "type": "integer"
                  }
                },
                "required": [
                  "bucket",
                  "requests",
                  "bytesBody",
                  "bytesBilled"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "bytesBilled": {
              "description": "Total billed bytes over the range.",
              "type": "integer"
            },
            "bytesBilledToVisitors": {
              "description": "How much of bytesBilled an authenticated visitor paid for rather than the owner. Zero unless the domain is on the sender-pays policy.",
              "type": "integer"
            },
            "domain": {
              "type": "string"
            },
            "headerEstimateBytes": {
              "description": "The flat per-response constant added to every logged body size. Every byte figure here is an estimate by this much per response.",
              "type": "integer"
            },
            "records": {
              "description": "Which published version of the site record served the traffic, heaviest first. Bounded by topRecords, so a domain republished more often than that has versions this does not list. Absent from a deployment that does not report the split.",
              "items": {
                "description": "One published version, and the traffic the snapshots built from it served.",
                "properties": {
                  "bytesBilled": {
                    "description": "Billed bytes.",
                    "type": "integer"
                  },
                  "firstSeen": {
                    "description": "The first response inside the range served from this version.",
                    "format": "datetime",
                    "type": "string"
                  },
                  "lastSeen": {
                    "description": "The last, which with firstSeen is how long the version was serving inside the range — what makes one version's byte figure comparable to another's. Absent where the answer is not known, which a reader shows as still serving rather than as an interval it was not given.",
                    "format": "datetime",
                    "type": "string"
                  },
                  "recordCid": {
                    "description": "The site record the serving snapshot was built from. Every response already names it, so the split needs nothing tagged.",
                    "format": "cid",
                    "type": "string"
                  },
                  "requests": {
                    "description": "Responses.",
                    "type": "integer"
                  }
                },
                "required": [
                  "recordCid",
                  "firstSeen",
                  "requests",
                  "bytesBilled"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "refusals": {
              "description": "What the bandwidth allowance refused over the range, and what serving it would have cost. Absent from a deployment that does not report it.",
              "properties": {
                "estimatedBytes": {
                  "description": "What serving those responses instead would have charged the owner. Absent unless the deployment records it: a refusal transferred no body, so its cost is in no logged size, and only the edge knows how large the path it refused would have been.",
                  "type": "integer"
                },
                "requests": {
                  "description": "Responses refused because the payer's allowance for the period was spent. The same responses the status mix counts as 402, taken from the same read so the two figures cannot disagree.",
                  "type": "integer"
                }
              },
              "required": [
                "requests"
              ],
              "type": "object"
            },
            "statuses": {
              "description": "The status mix, with the crawler share alongside it.",
              "items": {
                "description": "One status code's share of the requests and of the bytes.",
                "properties": {
                  "botRequests": {
                    "description": "How many of those came from a client classified as a crawler. Crawler traffic is billed, because it is real egress and the alternative rewards user-agent spoofing.",
                    "type": "integer"
                  },
                  "bytesBilled": {
                    "description": "Billed bytes.",
                    "type": "integer"
                  },
                  "requests": {
                    "description": "Responses with this status.",
                    "type": "integer"
                  },
                  "status": {
                    "description": "The HTTP status.",
                    "type": "integer"
                  }
                },
                "required": [
                  "status",
                  "requests",
                  "bytesBilled",
                  "botRequests"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "topPaths": {
              "description": "The busiest paths over the range.",
              "items": {
                "description": "One path and what it cost.",
                "properties": {
                  "bytesBilled": {
                    "description": "Billed bytes.",
                    "type": "integer"
                  },
                  "path": {
                    "description": "The request path.",
                    "type": "string"
                  },
                  "requests": {
                    "description": "Responses.",
                    "type": "integer"
                  }
                },
                "required": [
                  "path",
                  "requests",
                  "bytesBilled"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "domain",
            "bytesBilled",
            "bytesBilledToVisitors",
            "headerEstimateBytes",
            "buckets",
            "topPaths",
            "statuses"
          ],
          "type": "object"
        }
      },
      "parameters": {
        "properties": {
          "domain": {
            "description": "The registered hostname. Must be registered to the calling identity.",
            "maxLength": 253,
            "type": "string"
          },
          "from": {
            "description": "Inclusive lower bound. Defaults to 30 days ago.",
            "format": "datetime",
            "type": "string"
          },
          "to": {
            "description": "Exclusive upper bound. Defaults to now.",
            "format": "datetime",
            "type": "string"
          },
          "topPaths": {
            "default": 20,
            "description": "How many of the busiest paths to return.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          },
          "topRecords": {
            "default": 20,
            "description": "How many published record versions to return. A record CID is not a small set: a domain republished often has one per publish, so this is a top-N and not the whole history.",
            "maximum": 100,
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "domain"
        ],
        "type": "params"
      },
      "type": "query"
    }
  },
  "id": "space.highport.manage.getSiteTraffic",
  "lexicon": 1
}