--- title: "List facts in a POT" method: GET path: "/pots/{pot_id}/facts" tags: ["facts", "facts"] --- # List facts in a POT `GET /pots/{pot_id}/facts` List facts within a POT, with filtering (POT Score range, domain, tags, source document, status), sorting (created_at, updated_at, pot_score), and **cursor-based pagination**. Returns each fact with its current POT Score, level (e.g., `VERIFIED`, `SUPPORTED`), provenance, and an `edge_summary` block counting incoming/outgoing edges by type. **Common use cases:** - Browsing facts by certainty (`min_pot_score=0.8` for VERIFIED+). - Auditing a single source document's extracted facts (`document_id=...`). - Building a Curator review queue (filter by `status=pending`). - Powering an internal knowledge browser. **Pagination:** cursor-based. First request omits `cursor`; subsequent requests pass back the `next_cursor` from the prior response. Cursors are opaque tokens — do not parse or construct them. Changing filters or sort mid-pagination returns 400; start a new pagination from page 1. **Total count:** by default the response omits `total` (saves one Query per page). Pass `include_total=true` if you need it for a 'Showing N of M' display, or call `GET /pots/{pot_id}/stats` for richer counts. ## Path parameters - `pot_id` string, uuid, required ## Query parameters - `min_pot_score` number, nullable - `max_pot_score` number, nullable - `document_id` string, uuid, nullable — Filter by source document UUID - `domain` string, nullable - `status` string, nullable - `tags` string[] - `sort_by` 'created_at' | 'updated_at' | 'pot_score' - `sort_order` 'asc' | 'desc' - `limit` integer - `cursor` string, nullable — Opaque pagination cursor - `include_total` boolean — Set to true to include `total` in the response. Adds one Query per page; default is false for performance. ## Response `200` Facts retrieved successfully - FactListResponse — Response for list facts endpoint. Pagination is cursor-based. `next_cursor` is `null` on the last page and an opaque base64 string otherwise — pass it back as the `cursor` query param to fetch the next page. `total` is opt-in via `?include_total=true` on the route. Skipping the total halves the per-page RCU cost on the hot pagination path; callers that need the count for "Showing N of M" displays should opt in or call GET /pots/{pot_id}/stats instead. - `pot_id` string, uuid, required - `facts` FactExtended[], required - `id` string, uuid, required — Unique identifier (UUID) - `pot_id` string, uuid, required — POT this fact belongs to - `workspace_id` string, uuid, nullable — Multi-tenant isolation. Defaults to DEV_WORKSPACE_ID if None. - `content` string, required — The actual claim or statement - `title` string, nullable — Short title (max 50 chars, hard limit 80) for graph node labels. Generated by LLM during extraction. None for legacy facts. - `content_hash` string, nullable — SHA-256 hash of content for deduplication - `pot_score` number, required — Certainty score (0.0-1.0, where 1.0 = CONSTITUTION) - `original_pot_score` number, nullable — Pre-propagation POT Score. None if propagation hasn't run. - `level` 'CONSTITUTION' | 'VERIFIED' | 'SUPPORTED' | 'INFERRED' | 'HYPOTHESIS' | 'SPECULATION', required — POT Index levels matching score ranges. - `embedding_model` string, nullable — Embedding model used, e.g. text-embedding-3-small - `provenance` Provenance, required — Provenance information for a fact. - `type` string, required — Type of provenance (extracted, manual, inferred, imported) - `sources` object[] — Source documents or references - `derivation` object, nullable — Derivation info for inferred facts - `classification` Classification — Classification metadata for a fact. - `domain` string — Domain category - `subdomain` string, nullable — Subdomain category - `tags` string[] — Tags for search (max 20). Inherited from SourceMetadata.tags during ingestion. - `entity_mentions` string[] — Entities mentioned - `status` string — Processing status (processing, ready, error) - `validation_status` string — Validation status (pending, validated, disputed, rejected) - `created_at` string, date-time — When fact was created - `updated_at` string, date-time — When fact was last updated - `valid_from` string, date-time, nullable — When the fact started being true - `valid_until` string, date-time, nullable — When the fact stopped being true - `decay_rate` number, nullable — Temporal decay rate per month (null if no decay) - `document_id` string, uuid, nullable — Document UUID this fact was extracted from. None for constitution facts and inline ingestion. - `language` string, nullable — ISO 639-1 language code of the fact content (e.g. 'es', 'en'). Inherited from document language detection during extraction. - `location` DocumentLocation — Location metadata tracing a fact back to its source in the document. Populated during ingestion when document_index_enabled=True. Available fields depend on document format: - PDF: page_number, section_path, source_text - DOCX: section_path, source_text (no page_number without LibreOffice) - PPTX: page_number (slide), section_path, source_text - XLSX: sheet_name, row_number, cell_ref, source_text - MD/TXT: section_path, source_text - `page_number` integer, nullable — Page number (1-indexed). PDF: page. PPTX: slide number. - `section_path` string, nullable — Heading breadcrumb, e.g. '## Resultados > ### Q3 2024'. - `source_text` string, nullable — Verbatim text excerpt from the document this fact was derived from. - `sheet_name` string, nullable — XLSX sheet (tab) name where the fact was found. - `row_number` integer, nullable — XLSX row number (1-indexed). - `cell_ref` string, nullable — XLSX cell reference, e.g. 'B7' or 'B7:D7'. - `scope_inferred` 'own' | 'third_party' | 'mixed_context' | 'unknown', nullable — Per-fact scope classification from scope-aware extraction. 'own' = describes the operating organization's data; 'third_party' = describes external entities (case studies, customers); 'mixed_context' = blends first- and third-party content; 'unknown' = LLM could not determine. None = legacy fact, extraction predates scope-aware prompt. - `scope_confidence` number, nullable — LLM-reported confidence (0.0-1.0) on the scope_inferred classification. ≥0.7 = trust; 0.4-0.7 = hint; <0.4 = manually verify. None when scope_inferred is None. - `scope_reason` string, nullable — Short LLM-generated explanation of the scope_inferred classification (why this scope, what signal the LLM used). Used by KB2B tooltip to explain confidence to admins. None when scope_inferred is None. - `context_attachment_ids_used` string[], nullable — Snapshot of context_attachment_ids in scope at extraction time. Empty list = extraction ran under M21+ with zero attachments. None = legacy fact (pre-M21) or non-extraction-pipeline fact. - `version` integer — Version number (increments on update) - `flags` string[] — Special flags (needs_review, deprecated, etc.) - `notes` string, nullable — Internal notes - `edge_summary` EdgeSummary — Denormalized edge count summary stored on each fact. Enables KB2B to display edge counts per fact without extra API calls. Updated atomically when edges are created or deleted. - `total_in` integer — Total incoming edges - `total_out` integer — Total outgoing edges - `by_type` object — Edge counts broken down by type (e.g. supports, contradicts) - `total` integer, nullable — Total facts matching filters (uncapped). Only populated when the request opts in via `?include_total=true`. - `limit` integer, required — Page size requested - `next_cursor` string, nullable — Opaque cursor for the next page, or null when there are no more results. - `has_more` boolean, required — Whether more results exist beyond this page ## Other responses - `400` — Cursor is malformed, cross-tenant, or stale - `404` — POT not found in this workspace - `422` — Validation Error --- [API](https://skmtc.dev/scipot/apis/scipot-core-api.md) · [All operations](https://skmtc.dev/scipot/apis/scipot-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scipot/scipot-core-api/revisions/e8712e9ffeae/schema)