pet.trezy.getPets Documentation (EN)

main query

The at-uris of a player's pets, newest first, optionally filtered by state. Returns IDENTIFIERS ONLY — hydrate each one with pet.trezy.getPet?aturi=. Splitting it that way keeps the list cheap for a player who has collected a great many pets, where sending every record would be most of the payload and almost none of it drawn. The stage needs at most activePetCap of them, so it pays one list call and a handful of hydrations.

Parameters

cursor string Optional

From a previous response. Keyset, not an offset: it names the last row seen, so a pet bought mid-scroll cannot shift the page under the reader or make one disappear.

did string did Required

Whose pets. Public, like getPet and getStats — a player's collection is visible on their profile page.

limit integer Optional

How many at-uris to return.

state array of string Optional

Which states to include. Omitted means all three. Repeat the parameter to combine them: ?state=inactive&state=retired. The three are mutually exclusive — retiring forces a pet inactive, so `retired` and `inactive` never both describe one pet.

Output

Encodingapplication/json

cursor string Optional

Present only when another page may exist. ABSENT MEANS THE END, so a client that keeps scrolling until the cursor is gone terminates; a client that stops when `pets` is empty also terminates, one call later.

error string Optional

Present instead of the list. A stable machine code. `unavailable` means the ledger could not be READ — which is emphatically not the same as owning no pets, and must never be rendered as an empty collection. Returning [] there would tell a player their pets are gone.

Known values: bad-did, unknown-state, bad-cursor, unavailable

message string Optional

No description available.

pets array Optional

At-uris, newest first. Ordered by createdAt then uri so the order is total — two pets bought in the same instant would otherwise be free to swap places between pages, which is how a keyset cursor loses or repeats a row.

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://api.bsky.social)

Parameters

cursor From a previous response. Keyset, not an offset: it names the last row seen, so a pet bought mid-scroll cannot shift the page under the reader or make one disappear.

did * Whose pets. Public, like getPet and getStats — a player's collection is visible on their profile page.

limit How many at-uris to return.

state Which states to include. Omitted means all three. Repeat the parameter to combine them: ?state=inactive&state=retired. The three are mutually exclusive — retiring forces a pet inactive, so `retired` and `inactive` never both describe one pet.

View raw schema

{
  "type": "query",
  "output": {
    "schema": {
      "type": "object",
      "required": [],
      "properties": {
        "pets": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "at-uri"
          },
          "description": "At-uris, newest first. Ordered by createdAt then uri so the order is total — two pets bought in the same instant would otherwise be free to swap places between pages, which is how a keyset cursor loses or repeats a row."
        },
        "error": {
          "type": "string",
          "description": "Present instead of the list. A stable machine code. `unavailable` means the ledger could not be READ — which is emphatically not the same as owning no pets, and must never be rendered as an empty collection. Returning [] there would tell a player their pets are gone.",
          "knownValues": [
            "bad-did",
            "unknown-state",
            "bad-cursor",
            "unavailable"
          ]
        },
        "cursor": {
          "type": "string",
          "description": "Present only when another page may exist. ABSENT MEANS THE END, so a client that keeps scrolling until the cursor is gone terminates; a client that stops when `pets` is empty also terminates, one call later."
        },
        "message": {
          "type": "string"
        }
      }
    },
    "encoding": "application/json"
  },
  "parameters": {
    "type": "params",
    "required": [
      "did"
    ],
    "properties": {
      "did": {
        "type": "string",
        "format": "did",
        "description": "Whose pets. Public, like getPet and getStats — a player's collection is visible on their profile page."
      },
      "limit": {
        "type": "integer",
        "default": 50,
        "maximum": 100,
        "minimum": 1,
        "description": "How many at-uris to return."
      },
      "state": {
        "type": "array",
        "items": {
          "type": "string",
          "knownValues": [
            "active",
            "inactive",
            "retired"
          ]
        },
        "description": "Which states to include. Omitted means all three. Repeat the parameter to combine them: ?state=inactive&state=retired. The three are mutually exclusive — retiring forces a pet inactive, so `retired` and `inactive` never both describe one pet."
      },
      "cursor": {
        "type": "string",
        "description": "From a previous response. Keyset, not an offset: it names the last row seen, so a pet bought mid-scroll cannot shift the page under the reader or make one disappear."
      }
    }
  },
  "description": "The at-uris of a player's pets, newest first, optionally filtered by state. Returns IDENTIFIERS ONLY — hydrate each one with pet.trezy.getPet?aturi=. Splitting it that way keeps the list cheap for a player who has collected a great many pets, where sending every record would be most of the payload and almost none of it drawn. The stage needs at most activePetCap of them, so it pays one list call and a handful of hydrations."
}