---
title: "List Facts"
method: GET
path: "/v1/facts"
tags: ["v1"]
---

# List Facts

`GET /v1/facts`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/facts`
- Auth: HTTP bearer

The typed facts, a page at a time, filtered by end user, agent,
subject (`subject`), either side (`entity`) and relation (`predicate`,
`predicate_family`). A database read: no model is asked.

By default the facts true now. `as_of` gives the facts true at a date,
`known_as_of` the facts as the store knew them at a moment, and
`include_invalidated=true` adds the facts that ended, each with its
`invalid_at` and the `invalidated_by` that closed it.

## Query parameters

- `user_id` string, nullable: Filter to one end user.
- `agent_id` string, nullable
- `subject` string, nullable: Match the subject side.
- `entity` string, nullable: Match subject OR object side.
- `predicate` string, nullable
- `predicate_family` string, nullable
- `include_invalidated` boolean
- `as_of` string, nullable: ISO date/datetime: point-in-time validity.
- `known_as_of` string, nullable: ISO date/datetime: the facts as the store knew them then: learned by then, with the ends learned by then, true at `as_of` (default: that same moment). A move made in September and told in October: `as_of` September returns the new address, `known_as_of` September the old one.
- `limit` integer
- `offset` integer
- `exclude_sessions` boolean: Leave out the facts only work sessions state (memories written with `kind: session`, what a coding assistant's hooks save). Default false.

## Response `200`

Successful Response

- FactsResponse
  - `facts` Fact[], required
    - `id` string, required: The fact's `fct_` id.
    - `subject` string, required: The subject as it was written.
    - `subject_type` string, nullable: What the subject is: self, a person, an organization...
    - `predicate` string, required: The relation, canonical: `lives_in`.
    - `predicate_raw` string, required: The relation as it was extracted.
    - `object` string, required: The object as it was written.
    - `object_is_literal` boolean, required: True for a value (a date, an amount), false for an entity.
    - `predicate_family` string, nullable: The relation's family: `location`, `role`...
    - `confidence` number, nullable
    - `user_id` string, nullable: The end user the fact belongs to.
    - `agent_id` string, nullable: The agent namespace it was written under.
    - `valid_from` string, nullable: When it became true in the world.
    - `invalid_at` string, nullable: When it stopped being true. Null while it holds, and, read with `known_as_of`, while the store had not learned the end yet.
    - `invalidated_by` string, nullable: The `fct_` id of the fact that closed it.
    - `source_memory_id` string, nullable: The memory it was extracted from.
    - `created_at` string, nullable: When the store learned the fact.
    - `closed_known_at` string, nullable: When the store learned the fact had ended. Null while it is open.
    - `subject_canonical` string, required: The subject's current name, after its aliases.
    - `object_canonical` string, required: The object's current name, after its aliases.
    - `tense` string, required: What the text said: current, past or planned.
    - `last_confirmed_at` string, nullable: The last time a memory said it again.
    - `observation_count` integer, required: How many memories said it.
    - `source_memory_ids` string[], required: Every memory that said it.
  - `total` integer, required

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

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