---
title: "The runs (individual program invocations) behind a machine's events"
method: GET
path: "/api/runs/"
tags: ["Events"]
---

# The runs (individual program invocations) behind a machine's events

`GET /api/runs/`

## Request

- Base URL: `https://eyalsec.com`
- URL: `https://eyalsec.com/api/runs/`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in cookie `__Host-es2session`

Returns a machine's runs, newest first: one entry per invocation of an instrumented program, with what was run, when it was first and last seen reporting, how many distinct events it produced and how many occurrences those add up to. Values that look like passwords, tokens or keys are masked in the command line. Use run_uid with the events query's advanced builder - {"field":"run","op":"is","value":"<run_uid>"} on the python view - to narrow the events list, an export or the map to that one run; under that filter the count on each event is that run's own occurrences rather than the event's all-time total. A run_uid is empty on runs reported by agents that predate run ids, which are grouped by command line and environment instead: several invocations then share one entry. Ownership is a predicate in the query, so a machine secret belonging to another account returns an empty list, never that account's runs. Page with next_before: pass it back as before until it comes back empty.

This is a **read**: a read-only API key may call it.

## Query parameters

- `secret` string, uuid
- `machine` string
- `q` string
- `before` string
- `limit` integer

## Response `200`

OK.

- object

## Other responses

- `401`: The API key is missing, wrong, revoked or expired.
- `429`: A rate limit was hit, or the account is locked after wrong passwords. Retry-After gives the seconds to wait.
- `default`: An error. Check the status first; the body carries a short message, as JSON ({"error": "..."}) on most endpoints and as plain text on some. 400: malformed JSON, an invalid regex, an unreadable cursor or date, or an unknown value. 401: the API key is missing, wrong, revoked or expired. 403: a failed CSRF check, a read-only key trying to write, a product or feature not enabled on your account, a wrong password, or a write on an account limited to reading. 404: not found, including things that belong to another account. 409: conflict with the current state. 422: a field is missing or invalid. 429: a rate limit was hit, or the account is locked after wrong passwords. 500: something failed on our side.

---

[API](https://skmtc.dev/eyalsec/apis/eyalsec-api.md) · [All operations](https://skmtc.dev/eyalsec/apis/eyalsec-api/llms.txt) · [OpenAPI document](https://skmtc.dev/eyalsec/apis/eyalsec-api/revisions/dc7520689cf1?raw)