Skip to main content

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.

All list and search methods return a SignaList<T> — a paginated response that supports three consumption patterns. The first page is fetched eagerly; subsequent pages are fetched lazily as you consume them.

​
Async Iteration

The simplest approach. Iterate across all pages automatically with for await: 
for await (const tm of signa.trademarks.list({ offices: ['uspto'] })) {
  console.log(tm.mark_text);
}
This fetches the next page transparently when the current page is exhausted. Pages are fetched one at a time — no unnecessary requests.

​
Collect to Array

Fetch all items into a single array with toArray(): 
const allMarks = await signa.trademarks
  .list({ jurisdictions: ['US'], status_primary: 'active' })
  .then(list => list.toArray());

console.log(`Got ${allMarks.length} trademarks`);
A safety cap of 10,000 items is applied by default. Override it when you need more (or fewer): 
// Collect at most 500
const marks = await signa.trademarks
  .list({ offices: ['euipo'] })
  .then(list => list.toArray({ limit: 500 }));

​
Manual Paging

For full control — inspect each page, access metadata, decide whether to continue: 
let page = await signa.trademarks.list({ offices: ['uspto'], limit: 100 });

console.log(`Page 1: ${page.data.length} items`);
console.log(`Request ID: ${page.request_id}`);
console.log(`More pages? ${page.has_more}`);

while (page.has_more) {
  page = await page.getNextPage();
  console.log(`Next page: ${page.data.length} items`);
}
When there are no more pages, getNextPage() returns an empty list (not an error).

​
Page Properties

Every SignaList exposes:
PropertyTypeDescription
dataT[]Items in the current page
has_morebooleanWhether more pages exist
request_idstringUnique request ID for debugging
search_metaSearchMeta?Total count and timing (search responses only)
aggregationsRecord<string, Record<string, number>>?Faceted counts (search responses only)

​
Page Size

Control the number of items per page with the limit parameter: 
// 25 items per page (default varies by endpoint)
const page = await signa.trademarks.list({ offices: ['uspto'], limit: 25 });

​
Search-Specific Metadata

Search responses include additional metadata not present on regular list responses: 
const results = await signa.trademarks.search({
  query: 'APPLE',
  options: {
    include_total: true,
    include_timing: true,
    aggregations: ['office_code'],
  },
});

// Search metadata
console.log(results.search_meta?.total);   // 4521
console.log(results.search_meta?.took_ms); // 42

// Aggregation buckets
console.log(results.aggregations?.office_code);
// { uspto: 342, euipo: 156, wipo: 89, ... }

​
Cursor-Based

Signa uses cursor-based pagination (not offset-based). This means:
  • Results are stable even if new data is ingested between pages
  • You cannot jump to an arbitrary page number
  • Cursors are opaque strings — don’t parse or construct them
If you need to resume pagination later, store the cursor from the last page and pass it when you restart: 
// Save the cursor
const page = await signa.trademarks.list({ offices: ['uspto'], limit: 100 });
// ... process page.data ...
// The cursor is internal to SignaList — use getNextPage() to advance

​
Common Patterns

For full data syncs, store the last cursor to enable resume-on-failure:
let cursor: string | undefined = loadCheckpoint(); // from database or file

while (true) {
  const page = await signa.trademarks.list({ limit: 100, cursor });

  for (const trademark of page.data) {
    await upsertToLocalDb(trademark);
  }

  saveCheckpoint(page.pagination.cursor); // persist cursor

  if (!page.has_more) break;
  cursor = page.pagination.cursor;
}
Request the total on the first page only, then track progress as you paginate:
const firstPage = await signa.trademarks.list({
  limit: 100,
  include_total: true,
});

let processed = firstPage.data.length;
const total = firstPage.pagination.total_count;
console.log(`Processing ${processed}/${total}...`);

let cursor = firstPage.pagination.cursor;

while (cursor) {
  const page = await signa.trademarks.list({ limit: 100, cursor });
  processed += page.data.length;
  console.log(`Processing ${processed}/${total}...`);
  cursor = page.has_more ? page.pagination.cursor : undefined;
}
If processing each page is slow (e.g., enrichment), prefetch the next page while processing the current one:
let nextPagePromise = signa.trademarks.list({ limit: 100 });

while (true) {
  const page = await nextPagePromise;

  if (page.has_more && page.pagination.cursor) {
    nextPagePromise = signa.trademarks.list({
      limit: 100,
      cursor: page.pagination.cursor,
    });
  }

  await processPage(page.data);

  if (!page.has_more) break;
}