Skip to main content
GET
/
api
/
v1
/
agents
/
{ref}
/
events
List events
curl --request GET \
  --url https://gateway.sanfoundation.com/api/v1/agents/{ref}/events \
  --header 'x-api-key: <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

​
x-api-key
string
header
required

SAN-issued API key (sk_…) issued from the SAN Agents Dashboard (Settings → API Keys). Used by every /api/v1/* endpoint; usage is billed in credits against the owning account's active Stripe subscription.

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