Skip to main content

Entities resource

The mappa.entities resource provides methods for retrieving and updating speaker entities.

Overview​

Entities represent individual speakers identified by voiceprints across recordings.

  • Get a single entity by ID
  • List entities with cursor-based pagination
  • Iterate all entities with an async iterator
  • Update entity labels

Methods​

get()​

Get one entity.

const entity = await mappa.entities.get("ent_abc123xyz");

console.info(`Entity ID: ${entity.id}`);
console.info(`Label: ${entity.label ?? "(none)"}`);
console.info(`Recordings: ${entity.mediaCount}`);

Parameters​

get(
  entityId: string,
  opts?: {
    requestId?: string;
    signal?: AbortSignal;
  }
): Promise<Entity>

Returns​

{
  id: string;
  label: string | null;
  createdAt: string;
  mediaCount: number;
  lastSeenAt: string | null;
}

list()​

List entities with cursor pagination.

const page = await mappa.entities.list({ limit: 20 });

for (const entity of page.entities) {
  console.info(`${entity.id}: ${entity.label ?? "(none)"}`);
}

if (page.hasMore) {
  const nextPage = await mappa.entities.list({
    cursor: page.cursor,
    limit: 20,
  });
}

Parameters​

{
  limit?: number;
  cursor?: string;
  requestId?: string;
  signal?: AbortSignal;
}

Returns​

{
  entities: Entity[];
  cursor: string | null;
  hasMore: boolean;
}

listAll()​

Async iterator for all entities.

for await (const entity of mappa.entities.listAll({ limit: 100 })) {
  console.info(`Entity ${entity.id} has ${entity.mediaCount} recordings`);
}

Parameters​

{
  limit?: number;
  requestId?: string;
  signal?: AbortSignal;
}

update()​

Set or clear an entity label.

const updated = await mappa.entities.update("ent_abc123xyz", {
  label: "Candidate - John Doe",
});

console.info(updated.label);

Clear label:

await mappa.entities.update("ent_abc123xyz", { label: null });

Parameters​

update(
  entityId: string,
  body: {
    label?: string | null;
  },
  opts?: {
    requestId?: string;
    signal?: AbortSignal;
  }
): Promise<Entity>

Common patterns​

Capture entity ID from a report​

const report = await mappa.reports.generateFromUrl({
  url: "https://example.com/interview.mp3",
  output: { template: "hiring_report" },
  target: {
    strategy: "magic_hint",
    hint: "the candidate",
  },
});

const entityId = report.entity?.id;
if (entityId) {
  await mappa.entities.update(entityId, { label: "candidate:john-doe" });
}

Paginate all entities​

let cursor: string | undefined;
const all: Entity[] = [];

do {
  const page = await mappa.entities.list({ cursor, limit: 100 });
  all.push(...page.entities);
  cursor = page.cursor ?? undefined;
} while (cursor);

console.info(`Total entities: ${all.length}`);

Find high-activity speakers​

for await (const entity of mappa.entities.listAll()) {
  if (entity.mediaCount > 100) {
    console.info(`High activity: ${entity.id} (${entity.mediaCount} recordings)`);
  }
}

Type reference​

import type {
  Entity,
  ListEntitiesResponse,
} from "@mappa-ai/mappa-node";

See TypeScript Types for complete type definitions.

Next steps​