> For the complete documentation index, see [llms.txt](https://docs.urbit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.urbit.org/urbit-os/kernel/ames/scry.md).

# Ames Scry Reference

Ames scry reference - network queries for peers, routes, message flows, bones, and ship connectivity information.

Here are the scry endpoints of Ames. All of them take a `%x` `$care` and require the `$desk` in the path prefix be empty, so the general format is `.^([type] %ax /=//=/[some-path])`.

## /protocol/version <a href="#protocolversion" id="protocolversion"></a>

A scry with a `%x` `$care` and a `$path` of `/protocol/version` will return the current Ames protocol version as a `@`.

#### Example

```
> .^(@ %ax /=//=/protocol/version)
0
```

## /peers <a href="#peers" id="peers"></a>

A scry with a `%x` `$care` and a `$path` of `/peers` will return all ships that Ames is aware of. The type returned is a `(map ship ?(%alien %known))`, where `%known` means we have PKI data for them and `%alien` means we don't.

#### Example

```
> .^((map ship ?(%alien %known)) %ax /=//=/peers)
{[p=~wet q=%known] [p=~nes q=%known]}
```

## /peers/\[ship] <a href="#peersship" id="peersship"></a>

A scry with a `%x` `$care` and a `$path` of `/peers/[ship]` where `[ship]` is a ship name like `~dopzod` will return everything Ames knows about that ship, or crash if the ship is unknown to Ames. The type returned is a [`$ship-state`](/urbit-os/kernel/ames/data-types.md#ship-state).

#### Example

```
> .^(ship-state:ames %ax /=//=/peers/~nes)
[ %known
  [ symmetric-key=0wEF.5-Mp4.ehBxk.a-ktl.CAUHq.~XNVq.AfPFk.TwBbj.rc7MS
    life=1
    public-key=0w9R.IG6Km.CQfuL.lP9Da.l~kh1.lOHzV.xactk.1ybiB.hekW~.VC2d0.DDRsU.h6GHl.PKmRX.p3u2-.vO4Hg.QTOlp.A4AI0.uGPVy
    sponsor=~nes
  ]
  route=[~ [direct=%.y lane=[%.y p=~nes]]]
  qos=[%dead last-contact=~2021.8.9..16.11.36..fdbc]
    ossuary
  [ next-bone=4
    by-duct={[p=~[/gall/sys/way/~nes/hood /gall/use/hood/0w2.4d7EV/out/~nes/hood/helm/hi/~nes /dill //term/1] q=0]}
    by-bone={[p=0 q=~[/gall/sys/way/~nes/hood /gall/use/hood/0w2.4d7EV/out/~nes/hood/helm/hi/~nes /dill //term/1]]}
  ]
    snd
  { [ p=0
        q
      [ current=2
        next=3
        unsent-messages={}
        unsent-fragments=~
        queued-message-acks={}
          packet-pump-state
        [ next-wake=[~ ~2021.8.17..02.21.14..3d23]
          live={[[message-num=2 fragment-num=0] [last-sent=~2021.8.17..02.19.14..3d23 retries=2.255 skips=0] num-fragments=1 fragment=0w2.QJ1qS.JzaQn.w7rMp.IzuTJ.7M7aP.-1s~1]}
          metrics=[rto=~m2 rtt=~s1 rttvar=~s1 ssthresh=1 cwnd=1 num-live=1 counter=1]
        ]
      ]
    ]
  }
  rcv={}
  nax={}
  closing={}
  corked={}
  keens={}
  chain={}
  tip={}
  halt={}
]
```

## /peers/\[ship]/forward-lane <a href="#peersshipforward-lane" id="peersshipforward-lane"></a>

A scry with a `%x` `$care` and a `$path` of `/peers/[ship]/forward-lane` where `[ship]` is a ship name like `~dopzod` will return outbound routes to the given ship, or `~` if there are none. The type returned is a `(list lane:ames)`, see [`$lane`](/urbit-os/kernel/ames/data-types.md#lane) for type details.

#### Examples

```
> .^((list lane:ames) %ax /=//=/peers/~nes/forward-lane)
~[[%.y p=~nes]]
```

```
> .^((list lane:ames) %ax /=//=/peers/~nec/forward-lane)
~
```

## /bones/\[ship] <a href="#bonesship" id="bonesship"></a>

A scry with a `%x` `$care` and a `$path` of `/bones/[ship]` where `[ship]` is a ship name like `~dopzod` will return inbound and outbound [`$bone`](/urbit-os/kernel/ames/data-types.md#bone)s, which index message flows. If the ship in question is unknown to Ames, the scry will fail. The type returned is `[snd=(set bone) rcv=(set bone)]`.

#### Example

```
> .^([snd=(set bone) rcv=(set bone)] %ax /=//=/bones/~nes)
[snd={0} rcv={}]
```

## /snd-bones/\[ship]/\[bone] <a href="#snd-bonesshipbone" id="snd-bonesshipbone"></a>

A scry with a `%x` `$care` and a `$path` of `/snd-bones/[ship]/[bone]`, where `[ship]` is a ship name like `~dopzod` and `[bone]` is an outbound [`$bone`](/urbit-os/kernel/ames/data-types.md#bone), will return message flow details for that `$bone`. If the ship in question is unknown to Ames or the `$bone` does not exist, the scry will fail. The type returned is a [`$message-pump-state`](/urbit-os/kernel/ames/data-types.md#message-pump-state) wrapped in a `$vase`.

#### Example

```
> !<  message-pump-state:ames  .^(vase %ax /=//=/snd-bones/~nes/0)
[ current=2
  next=3
  unsent-messages={}
  unsent-fragments=~
  queued-message-acks={}
    packet-pump-state
  [ next-wake=[~ ~2021.8.17..02.27.14..aaff]
      live
    { [ [message-num=2 fragment-num=0]
        [last-sent=~2021.8.17..02.25.14..aaff retries=2.258 skips=0]
        num-fragments=1
        fragment=0w2.QJ1qS.JzaQn.w7rMp.IzuTJ.7M7aP.-1s~1
      ]
    }
    metrics=[rto=~m2 rtt=~s1 rttvar=~s1 ssthresh=1 cwnd=1 num-live=1 counter=1]
  ]
]
```

## /snubbed <a href="#snubbed" id="snubbed"></a>

A scry with a `%x` `$care` and a `$path` of `/snubbed` will return Ames' current ship whitelist/blacklist. The type is a `[form=?(%allow %deny) ships=(list ship)]`, where `+form` says whether it's a whitelist or blacklist and `.ships` are the ships on that list.

#### Example

```
> |ames/snub %deny ~wet ~sampel
>=

> .^([form=?(%allow %deny) ships=(list ship)] %ax /=//=/snubbed)
[form=%deny ships=[i=~sampel t=[i=~wet t=~]]]
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.urbit.org/urbit-os/kernel/ames/scry.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.