network.bsky.jetstream.planSnapshot Documentation (EN)

Build a download plan for the desired data pattern. The plan lists whole segments or block ranges that might contain events for the requested kinds, DIDs, and collections.

main procedure

Build a download plan for the desired data pattern. The plan lists whole segments or block ranges that might contain events for the requested kinds, DIDs, and collections.

Input

Encodingapplication/json

afterSeq integer Optional

Start after this sequence number. Events at or below it are not included.

minimum: 0

beforeSeq integer Optional

Stop at this sequence number. Events above it are not included.

minimum: 0

collections array Optional

Collection NSIDs or namespace wildcards such as app.bsky.feed.*; constrains commit events only. Non-commit kinds are unaffected, so combine with kinds=commit for a commits-only collection plan. Rejected when kinds is set and excludes commit. Omit or pass an empty array to include all collections.

maxLength: 100 items

dids array Optional

Only include data for these DIDs. Omit this field or pass an empty array to include all DIDs.

maxLength: 10000 items

kinds array Optional

Event kinds to include. Omit this field or pass an empty array to include all kinds.

maxLength: 4 items

Output

Encodingapplication/json

plannedThroughSeq integer Required

The last sealed sequence covered by this page. Use this value as afterSeq for the next page. If the response hits the server's page limit, this is the maxSeq of the last item returned; otherwise it equals sealedTipSeq. Planning is complete when plannedThroughSeq reaches sealedTipSeq.

sealedTipSeq integer Required

The end of the sealed archive for this snapshot, capped by beforeSeq when provided. Use this value as beforeSeq on later pages so the snapshot does not move while it is being downloaded.

segments array Required

No description available.

stats ref#stats Required

No description available.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://bsky.social)

Request Body (JSON) Enter valid JSON for the request body

View raw schema

{
  "type": "procedure",
  "input": {
    "schema": {
      "type": "object",
      "properties": {
        "dids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "did"
          },
          "maxLength": 10000,
          "description": "Only include data for these DIDs. Omit this field or pass an empty array to include all DIDs."
        },
        "kinds": {
          "type": "array",
          "items": {
            "enum": [
              "commit",
              "identity",
              "account",
              "sync"
            ],
            "type": "string"
          },
          "maxLength": 4,
          "description": "Event kinds to include. Omit this field or pass an empty array to include all kinds."
        },
        "afterSeq": {
          "type": "integer",
          "minimum": 0,
          "description": "Start after this sequence number. Events at or below it are not included."
        },
        "beforeSeq": {
          "type": "integer",
          "minimum": 0,
          "description": "Stop at this sequence number. Events above it are not included."
        },
        "collections": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxLength": 100,
          "description": "Collection NSIDs or namespace wildcards such as app.bsky.feed.*; constrains commit events only. Non-commit kinds are unaffected, so combine with kinds=commit for a commits-only collection plan. Rejected when kinds is set and excludes commit. Omit or pass an empty array to include all collections."
        }
      }
    },
    "encoding": "application/json"
  },
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "plannedThroughSeq",
        "sealedTipSeq",
        "segments",
        "stats"
      ],
      "properties": {
        "stats": {
          "ref": "#stats",
          "type": "ref"
        },
        "segments": {
          "type": "array",
          "items": {
            "ref": "#segment",
            "type": "ref"
          }
        },
        "sealedTipSeq": {
          "type": "integer",
          "minimum": 0,
          "description": "The end of the sealed archive for this snapshot, capped by beforeSeq when provided. Use this value as beforeSeq on later pages so the snapshot does not move while it is being downloaded."
        },
        "plannedThroughSeq": {
          "type": "integer",
          "minimum": 0,
          "description": "The last sealed sequence covered by this page. Use this value as afterSeq for the next page. If the response hits the server's page limit, this is the maxSeq of the last item returned; otherwise it equals sealedTipSeq. Planning is complete when plannedThroughSeq reaches sealedTipSeq."
        }
      }
    },
    "encoding": "application/json"
  },
  "description": "Build a download plan for the desired data pattern. The plan lists whole segments or block ranges that might contain events for the requested kinds, DIDs, and collections."
}

blockRange object

No description available.

Properties

first integer Required

Index of the first block in the range.

minimum: 0

last integer Required

Index of the last block in the range.

minimum: 0

View raw schema

{
  "type": "object",
  "required": [
    "first",
    "last"
  ],
  "properties": {
    "last": {
      "type": "integer",
      "minimum": 0,
      "description": "Index of the last block in the range."
    },
    "first": {
      "type": "integer",
      "minimum": 0,
      "description": "Index of the first block in the range."
    }
  }
}

segment object

No description available.

Properties

blocks array of ref#blockRange Optional

Block ranges to download, including both endpoints. This field is present only when mode is blocks.

checksum string Required

The segment's xxh3 metadata checksum, encoded as 16 hexadecimal characters.

maxLength: 16 bytesminLength: 16 bytes

index integer Required

Zero-based segment index.

minimum: 0

maxSeq integer Required

No description available.

minimum: 0

minSeq integer Required

No description available.

minimum: 0

mode string Required

How to download this segment. For segment, download the whole file with getSegment. For blocks, download the ranges listed in blocks with getBlock.

Known values: segment, blocks

name string Required

Segment filename to pass to getSegment or getBlock.

View raw schema

{
  "type": "object",
  "required": [
    "name",
    "index",
    "checksum",
    "minSeq",
    "maxSeq",
    "mode"
  ],
  "properties": {
    "mode": {
      "type": "string",
      "description": "How to download this segment. For segment, download the whole file with getSegment. For blocks, download the ranges listed in blocks with getBlock.",
      "knownValues": [
        "segment",
        "blocks"
      ]
    },
    "name": {
      "type": "string",
      "description": "Segment filename to pass to getSegment or getBlock."
    },
    "index": {
      "type": "integer",
      "minimum": 0,
      "description": "Zero-based segment index."
    },
    "blocks": {
      "type": "array",
      "items": {
        "ref": "#blockRange",
        "type": "ref"
      },
      "description": "Block ranges to download, including both endpoints. This field is present only when mode is blocks."
    },
    "maxSeq": {
      "type": "integer",
      "minimum": 0
    },
    "minSeq": {
      "type": "integer",
      "minimum": 0
    },
    "checksum": {
      "type": "string",
      "maxLength": 16,
      "minLength": 16,
      "description": "The segment's xxh3 metadata checksum, encoded as 16 hexadecimal characters."
    }
  }
}

stats object

No description available.

Properties

blocksMatched integer Required

No description available.

minimum: 0

entries integer Required

Number of items counted toward the server's per-page plan limit.

minimum: 0

segmentsExamined integer Required

No description available.

minimum: 0

segmentsMatched integer Required

No description available.

minimum: 0

View raw schema

{
  "type": "object",
  "required": [
    "segmentsExamined",
    "segmentsMatched",
    "blocksMatched",
    "entries"
  ],
  "properties": {
    "entries": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of items counted toward the server's per-page plan limit."
    },
    "blocksMatched": {
      "type": "integer",
      "minimum": 0
    },
    "segmentsMatched": {
      "type": "integer",
      "minimum": 0
    },
    "segmentsExamined": {
      "type": "integer",
      "minimum": 0
    }
  }
}