# space.highport.manage.getSiteTraffic

> Published by [lexicons.highport.space](https://lexicon.garden/identity/did:plc:ciygg5hma4q7ah2kxaszkyob)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.getSiteTraffic)
- [Documentation](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.getSiteTraffic/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:ciygg5hma4q7ah2kxaszkyob/space.highport.manage.getSiteTraffic/examples)

## Definitions

### `space.highport.manage.getSiteTraffic`

**Type**: `query`

Traffic to one of the caller's domains over a time range: hourly requests and bytes, the busiest paths, and status codes. Byte figures include a fixed per-response header estimate, since the edge logs only response bodies.

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `to` | `string` (datetime) | No | Exclusive upper bound. Defaults to now. |
| `from` | `string` (datetime) | No | Inclusive lower bound. Defaults to 30 days ago. |
| `domain` | `string` | Yes | The registered hostname. Must belong to the caller. |
| `topPaths` | `integer` | No | How many of the busiest paths to return. |
| `topRecords` | `integer` | No | How many record versions to return. A domain republished often has many, so this is a top N, not the full history. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `domain` | `string` | Yes |  |
| `buckets` | `array` | Yes | Hourly buckets, oldest first. |
| `records` | `array` | No | Which versions of the site record served the traffic, heaviest first. Limited to topRecords, so a frequently republished domain may have versions not listed. Absent if the deployment does not report it. |
| `refusals` | `object` | No | What the bandwidth allowance refused over the range, and what serving it would have cost. Absent if the deployment does not report it. |
| `statuses` | `array` | Yes | Requests by status code, with the crawler share. |
| `topPaths` | `array` | Yes | The busiest paths over the range. |
| `bytesBilled` | `integer` | Yes | Total bytes billed over the range. |
| `headerEstimateBytes` | `integer` | Yes | The fixed per-response header estimate added to each logged body size. Every byte figure here is estimated by this much per response. |
| `bytesBilledToVisitors` | `integer` | Yes | The part of bytesBilled that signed-in visitors paid instead of the owner. Zero unless the domain uses the visitor payer policy. |

#### Errors

- **InvalidDomain**: Not a valid, non-reserved, public-suffix-safe domain. Unlike DomainNotFound, the input is not a hostname at all.
- **DomainNotFound**: No such domain, or it does not belong to the caller. Both cases get the same error, so it cannot be used to check whether a domain exists.
- **AnalyticsDisabled**: No analytics store is configured, so no traffic was recorded.

## Raw Schema

```json
{
  "id": "space.highport.manage.getSiteTraffic",
  "defs": {
    "main": {
      "type": "query",
      "errors": [
        {
          "name": "InvalidDomain",
          "description": "Not a valid, non-reserved, public-suffix-safe domain. Unlike DomainNotFound, the input is not a hostname at all."
        },
        {
          "name": "DomainNotFound",
          "description": "No such domain, or it does not belong to the caller. Both cases get the same error, so it cannot be used to check whether a domain exists."
        },
        {
          "name": "AnalyticsDisabled",
          "description": "No analytics store is configured, so no traffic was recorded."
        }
      ],
      "output": {
        "schema": {
          "type": "object",
          "required": [
            "domain",
            "bytesBilled",
            "bytesBilledToVisitors",
            "headerEstimateBytes",
            "buckets",
            "topPaths",
            "statuses"
          ],
          "properties": {
            "domain": {
              "type": "string"
            },
            "buckets": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "bucket",
                  "requests",
                  "bytesBody",
                  "bytesBilled"
                ],
                "properties": {
                  "bucket": {
                    "type": "string",
                    "format": "datetime",
                    "description": "Start of the hour."
                  },
                  "requests": {
                    "type": "integer",
                    "description": "Responses in the hour."
                  },
                  "bytesBody": {
                    "type": "integer",
                    "description": "Response body bytes, as logged by the edge."
                  },
                  "botRequests": {
                    "type": "integer",
                    "description": "How many of requests came from crawlers. This is part of requests, not added to it. Bytes are not split this way. Absent if the deployment does not report it; show that as unknown, not as zero."
                  },
                  "bytesBilled": {
                    "type": "integer",
                    "description": "Body bytes plus the per-response header estimate."
                  }
                },
                "description": "One hour of a domain's traffic."
              },
              "description": "Hourly buckets, oldest first."
            },
            "records": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "recordCid",
                  "firstSeen",
                  "requests",
                  "bytesBilled"
                ],
                "properties": {
                  "lastSeen": {
                    "type": "string",
                    "format": "datetime",
                    "description": "The last response in the range served from this version. With firstSeen, it shows how long the version served, so byte figures can be compared across versions. Absent when unknown; show that as still serving."
                  },
                  "requests": {
                    "type": "integer",
                    "description": "Responses."
                  },
                  "firstSeen": {
                    "type": "string",
                    "format": "datetime",
                    "description": "The first response in the range served from this version."
                  },
                  "recordCid": {
                    "type": "string",
                    "format": "cid",
                    "description": "The site record the serving snapshot was built from."
                  },
                  "bytesBilled": {
                    "type": "integer",
                    "description": "Billed bytes."
                  }
                },
                "description": "One published version and the traffic it served."
              },
              "description": "Which versions of the site record served the traffic, heaviest first. Limited to topRecords, so a frequently republished domain may have versions not listed. Absent if the deployment does not report it."
            },
            "refusals": {
              "type": "object",
              "required": [
                "requests"
              ],
              "properties": {
                "requests": {
                  "type": "integer",
                  "description": "Responses refused because the payer's allowance for the period ran out. Matches the 402 count in statuses."
                },
                "estimatedBytes": {
                  "type": "integer",
                  "description": "What serving those responses would have cost the owner. Absent unless the deployment records it, because a refused response has no logged body size."
                }
              },
              "description": "What the bandwidth allowance refused over the range, and what serving it would have cost. Absent if the deployment does not report it."
            },
            "statuses": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "status",
                  "requests",
                  "bytesBilled",
                  "botRequests"
                ],
                "properties": {
                  "status": {
                    "type": "integer",
                    "description": "The HTTP status."
                  },
                  "requests": {
                    "type": "integer",
                    "description": "Responses with this status."
                  },
                  "botRequests": {
                    "type": "integer",
                    "description": "How many of those came from crawlers. Crawler traffic is billed: it is real egress, and not billing it would reward faking a user agent."
                  },
                  "bytesBilled": {
                    "type": "integer",
                    "description": "Billed bytes."
                  }
                },
                "description": "One status code's share of requests and bytes."
              },
              "description": "Requests by status code, with the crawler share."
            },
            "topPaths": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "path",
                  "requests",
                  "bytesBilled"
                ],
                "properties": {
                  "path": {
                    "type": "string",
                    "description": "The request path."
                  },
                  "requests": {
                    "type": "integer",
                    "description": "Responses."
                  },
                  "bytesBilled": {
                    "type": "integer",
                    "description": "Billed bytes."
                  }
                },
                "description": "One path and its traffic."
              },
              "description": "The busiest paths over the range."
            },
            "bytesBilled": {
              "type": "integer",
              "description": "Total bytes billed over the range."
            },
            "headerEstimateBytes": {
              "type": "integer",
              "description": "The fixed per-response header estimate added to each logged body size. Every byte figure here is estimated by this much per response."
            },
            "bytesBilledToVisitors": {
              "type": "integer",
              "description": "The part of bytesBilled that signed-in visitors paid instead of the owner. Zero unless the domain uses the visitor payer policy."
            }
          }
        },
        "encoding": "application/json"
      },
      "parameters": {
        "type": "params",
        "required": [
          "domain"
        ],
        "properties": {
          "to": {
            "type": "string",
            "format": "datetime",
            "description": "Exclusive upper bound. Defaults to now."
          },
          "from": {
            "type": "string",
            "format": "datetime",
            "description": "Inclusive lower bound. Defaults to 30 days ago."
          },
          "domain": {
            "type": "string",
            "maxLength": 253,
            "description": "The registered hostname. Must belong to the caller."
          },
          "topPaths": {
            "type": "integer",
            "default": 20,
            "maximum": 100,
            "minimum": 0,
            "description": "How many of the busiest paths to return."
          },
          "topRecords": {
            "type": "integer",
            "default": 20,
            "maximum": 100,
            "minimum": 0,
            "description": "How many record versions to return. A domain republished often has many, so this is a top N, not the full history."
          }
        }
      },
      "description": "Traffic to one of the caller's domains over a time range: hourly requests and bytes, the busiest paths, and status codes. Byte figures include a fixed per-response header estimate, since the edge logs only response bodies."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```