> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Analytics

> Retrieve a composed analytics report across an entity's resolved owner family

## When to use this

Audit a conglomerate's global trademark footprint across all its resolved subsidiaries in one call. The report deduplicates marks shared by multiple member owners and groups Madrid designations under their International Registration.

Reports use a Valkey cache with a 24-hour TTL backstop and are invalidated by the nightly stats-compute `entity.updated` wave. Proceedings ingestion does not emit owner-grain events directly, so a newly ingested proceeding appears within about 24 hours. `Server-Timing` reports `cache;desc="hit"` or `cache;desc="miss"`.

## Path Parameters

<ParamField path="id" type="string" required>Entity ID (`ent_*`).</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.signa.so/v1/entities/ent_R3jK9mN2/analytics \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });
  const report = await signa.entities.analytics("ent_R3jK9mN2");
  console.log(report.portfolio.mark_count, report.portfolio.active_count);
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "analytics_report",
    "subject": {
      "id": "ent_R3jK9mN2",
      "object": "entity",
      "name": "ACME HOLDINGS"
    },
    "portfolio": {
      "mark_count": 1842,
      "active_count": 1510,
      "dead_count": 318,
      "status_distribution": {
        "registered": 1510,
        "abandoned": 318,
        "unknown": 14
      },
      "class_distribution": {
        "9": 520
      },
      "jurisdiction_spread": {
        "US": 940
      },
      "filing_trend": {
        "2025": 96
      }
    },
    "litigation": {
      "subject": {
        "owner_id": null,
        "entity_id": "ent_R3jK9mN2"
      },
      "proceedings_total": 7,
      "as_challenger": {
        "total": 5,
        "by_type": {
          "opposition": 4,
          "cancellation": 1
        },
        "outcomes": {
          "challenger_won": 3,
          "challenger_lost": 1,
          "settled": 1
        },
        "decided": 4,
        "win_rate": 0.75,
        "avg_duration_days": 108.5
      },
      "as_defendant": {
        "total": 2,
        "by_type": {
          "opposition": 2
        },
        "outcomes": {
          "challenger_lost": 1,
          "pending": 1
        },
        "decided": 1,
        "win_rate": 1,
        "avg_duration_days": 92
      }
    },
    "transactions": {
      "transaction_count": 4,
      "by_type": {
        "assignment": 2,
        "security_interest": 1,
        "release": 1
      },
      "unreleased_security_interests": 0,
      "marks_with_liens": 0,
      "acquired_count": 2,
      "divested_count": 1,
      "first_transaction_date": "2019-06-15",
      "last_transaction_date": "2024-03-01"
    },
    "generated_at": "2026-07-12T08:00:00.000Z"
  }
  ```
</ResponseExample>

## Litigation fields

`as_challenger` covers disputes the entity's member owners brought as opponents or petitioners. `as_defendant` covers disputes against marks those owners currently hold. `win_rate` is wins divided by `decided`, and is `null` when `decided` is zero. `decided` excludes settled, withdrawn, and pending proceedings. `avg_duration_days` is the mean number of days from filing to decision when both dates are available.

## Transaction fields

`by_type` groups distinct family recordings into conveyance-type buckets. `acquired_count` counts recordings with a family owner as assignee; `divested_count` counts those with one as assignor. The first and last dates bound the recorded family transaction history.

`unreleased_security_interests` counts security-interest recordings without a non-purged release pointing back to the same reel/frame, and `marks_with_liens` deduplicates marks attached to those recordings. Reel/frame linkage is authoritative: a security interest remains unreleased until a release recording points to it.

Acquirers use this block to gauge a brand family's transaction history, while lenders check for unreleased liens before extending credit. See [list assignments](/api-reference/records/transactions/list-assignments), [get an assignment](/api-reference/records/transactions/get-assignment), and the [chain-of-title and lien diligence guide](/guides/chain-of-title-lien-diligence) for recording-level detail.

## Large entities

Entities resolve to at most 10,000 live member owners. Larger portfolios return `422 entity_too_large` with `error.reason` set to `member_owners_too_large`, plus `member_count` and `member_count_limit`.

If resolution exceeds the bounded corporate family graph walk instead, the same `422 entity_too_large` response uses `error.reason: family_graph_too_large`, plus `related_entity_limit` and `depth_limit`.