Skip to main content
GET
/
x402
/
v1
/
agents
/
{ref}
/
events
List events
curl --request GET \
  --url https://gateway.sanfoundation.com/x402/v1/agents/{ref}/events \
  --header 'Payment-Signature: <api-key>'
{ "agent": { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "externalId": "<string>", "name": "<string>", "slug": "<string>", "domain": "<string>", "description": "<string>" }, "count": 123, "events": [ { "eventId": "<string>", "title": "<string>", "summary": "<string>", "firstSeenAt": "2023-11-07T05:31:56Z", "lastUpdatedAt": "2023-11-07T05:31:56Z", "primaryAgent": "<string>", "eventType": "<string>", "status": "<string>", "tags": [ "<string>" ], "sourceCount": 123, "entities": [ { "name": "<string>", "type": "<string>", "role": "<string>" } ], "locations": [ { "name": "<string>", "country": "<string>" } ], "sources": [ { "url": "<string>", "publication": "<string>", "publishedAt": "2023-11-07T05:31:56Z" } ], "occurredAt": "2023-11-07T05:31:56Z" } ] }

Authorizations

​
Payment-Signature
string
header
required

Base64-encoded signed payment payload as defined by the x402 protocol. Omit on the first attempt to receive the 402 challenge in the PAYMENT-REQUIRED response header; include it on the retry to settle payment and receive the resource.

The legacy header name X-PAYMENT is also accepted by the server for backward compatibility — clients may send either, but Payment-Signature is preferred.

See x402.org for the on-the-wire shape of the PaymentRequired challenge and the settlement receipt returned in the PAYMENT-RESPONSE response header.

Path Parameters

​
ref
string
required

Flexible agent identifier. Accepts any of:

  • UUID — 488ed3ff-6a4d-42e5-8e24-44eeef77959c
  • Name (case-insensitive) — Noah, noah, NOAH
  • Slug — lowercase name with spaces as underscores
  • External ID — 017, 17, 069, 69 (# and zero-padding tolerated)

Query Parameters

​
limit
integer
default:10

Max number of events to return.

Required range: 1 <= x <= 30

Response

OK — recent canonical events for the agent.

​
agent
object
required
​
count
integer
required
​
events
object[]
required