---
title: "Get the report's entity map"
method: GET
path: "/v1/reports/{id}/entities"
tags: ["Reports"]
---

# Get the report's entity map

`GET /v1/reports/{id}/entities`

## Request

- Base URL: `https://api.squirrelscan.com`
- URL: `https://api.squirrelscan.com/v1/reports/{id}/entities`
- Auth: HTTP bearer

The graph of things the audited site declares in JSON-LD (Organization, Person, Product, Article, …), collapsed across every crawled page, with the references between them.

Filters apply BEFORE rendering, so `?type=Organization&format=markdown` renders a markdown document of Organizations rather than filtering a rendered string. `summary` always describes the WHOLE site even when a filter is applied; compare it against `meta.counts` to see whether you are holding a subset.

404 when the report predates the feature (no map was published with it), when it does not exist, or when it belongs to another organization. Available on every plan.

## Path parameters

- `id` string, required

## Query parameters

- `format` 'json' | 'jsonld' | 'html' | 'markdown' | 'csv' | 'dot' | 'graphml' | 'mermaid'
- `type` string
- `exclude_type` string[]
- `page` string
- `problem` 'no-id' | 'conflict' | 'dangling' | 'single-page' | 'split-identity'
- `q` string
- `include_page_local` 'true' | 'false' | '1' | '0'

## Response `200`

The entity map. `application/json` for `format=json`; otherwise the requested rendering, with a content type matching the format.

- EntityMapResponse: The entity-map document plus the context the endpoint adds under `meta`.
  - `format` 'squirrelscan/entity-map', required
  - `version` 1, required
  - `site` string, required: Site the audit started from.
  - `generatedAt` string, date-time, required
  - `summary` EntityMapSummary, required: Site-wide totals. Describes the WHOLE audit even when the response is filtered.
    - `nodeCount` integer, required
    - `edgeCount` integer, required
    - `danglingCount` integer, required: Edges pointing at an `@id` no crawled page declares.
    - `pagesTotal` integer, required
    - `pagesWithoutEntities` integer, required
    - `nodesWithStableId` integer, required: Entities carrying an `@id`.
    - `stableIdShare` number, required: nodesWithStableId as a 0-1 share of nodeCount.
    - `pageLocalCount` integer, required: Entities tagged `pageLocal` — what a graph hides by default.
    - `nodesWithoutIdCount` integer, required: Entities with no `@id` declared on more than one page: the identity finding. An entity seen on a single page is not counted.
    - `conflictCount` integer, required: Entities carrying at least one conflicting property. Counts entities, not properties.
    - `countsByType` object, required: Occurrence count per schema.org `@type`.
  - `nodes` EntityMapNode[], required
    - `key` string, required: Identity the builder settled on: the resolved `@id` when the site supplied one, otherwise a synthetic type+name key.
    - `id` string, nullable, required: The resolved `@id`, or null when the entity declared none.
    - `types` string[], required
    - `name` string, nullable, required
    - `properties` object, required: Consistency-relevant properties, normalised to strings.
      - `name` string
      - `url` string
      - `logo` string
      - `image` string[]
      - `sameAs` string[]
      - `telephone` string
      - `email` string
      - `address` string
      - `description` string
    - `occurrences` integer, required: How many times the entity was declared across the crawl.
    - `pages` string[], required: Declaring pages, sorted and capped; the remainder is in morePages.
    - `morePages` integer, required
    - `conflicts` object[], required: Properties whose value differs between occurrences.
      - `property` string, required
      - `values` object[], required
        - `value` string, required
        - `pages` string[], required
        - `morePages` integer, required
    - `danglingRefs` integer, required: Outgoing `@id` references from this node that nothing declares.
    - `pageLocal` boolean, required: True when the entity describes one page rather than the site's subject matter: Question, Answer, BreadcrumbList, ListItem, WebPage, and an ImageObject with no name. These are hidden unless `include_page_local` is set.
  - `edges` EntityMapEdge[], required
    - `source` string, required
    - `predicate` string, required: author, publisher, mainEntity, about, isPartOf, sameAs, logo, offers, …
    - `target` string, required
    - `dangling` boolean, required: True when no crawled page declares the target.
    - `occurrences` integer, required
    - `pages` string[], required
    - `morePages` integer, required
  - `pages` object[]: Per-page contributions. Empty on hosted maps: the published copy drops it and the summary carries what a reader needs from it.
    - `url` string
    - `declares` string[]
    - `references` string[]
    - `entityCount` integer
  - `meta` object, required
    - `reportId` string, required
    - `websiteId` string, nullable, required
    - `auditedAt` string, date-time, required
    - `filtered` boolean, required: True when a query filter removed at least one entity.
    - `counts` object, required: Post-filter totals. Compare against `summary` to see whether this is a subset.
      - `nodes` integer, required
      - `edges` integer, required
    - `pageFilterIncomplete` boolean, required: True when a `page` filter ran against a map containing an entity whose declaring-page list was capped. The result may be missing entities that really are declared on the requested page, because the omitted URLs are not in the document. Always false when no `page` filter was given.
    - `backfilled` string[], required: Summary counters that were RECONSTRUCTED because this map was published before the field existed, so they are estimates rather than site totals. `summary` normally describes the whole audited site while `nodes` may be a projection capped at 750 entities. A reconstructed counter can only be computed from the stored entities, so on a large site it reads low next to its un-reconstructed siblings. Render those fields as "at least N", or hide them, rather than as site totals. Empty on a map published by a current CLI. Entity-level `pageLocal` is reconstructed exactly and is never listed here.

## Other responses

- `400`: Request body or query failed validation. `error.issues` lists up to 10 failed fields (`{ path, message }`); when more failed, `error.truncated: true` and `error.totalIssues` indicate the full count.
- `401`: Missing or invalid credentials (including the shared auth middleware: no/invalid bearer token). Typed envelope with code `UNAUTHORIZED`. Branch on the `401` status, not the message.
- `403`: Authenticated but not permitted (e.g. not a member of the requested organization). Typed envelope; code `FORBIDDEN`, or `NO_ORG` when no active organization is resolved on credit/org-scoped routes. Branch on the `403` status.
- `404`: Resource not found (or hidden from the caller).
- `429`: Too many requests. Retry after the window resets. (Rate limiting is planned — issue #69 — these headers document the intended contract.)

---

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