Skip to main content
When you need data for many trademarks at once, batch endpoints let you retrieve up to 100 records in a single API call. This is significantly more efficient than making individual requests and reduces your rate limit consumption.

​
When to Use Batch vs. Individual

ScenarioRecommended Approach
Display a single trademark detail pageIndividual GET /v1/trademarks/:id
Hydrate a dashboard with 10—50 known IDsBatch POST /v1/trademarks/batch
Sync a portfolio of trademarks periodicallyBatch, chunked into groups of 100
Search for trademarks matching criteriaSearch POST /v1/trademarks/search
Iterate through all trademarks in your orgPaginated GET /v1/trademarks
A batch request of 50 IDs counts as one request against your rate limit, not 50. Use batches whenever you know the IDs upfront.

​
POST /v1/trademarks/batch

Fetch multiple trademarks by their IDs in a single request.

​
Request

POST /v1/trademarks/batch
{
  "ids": [
    "tm_7d4e1f2a",
    "tm_3b8c9d0e",
    "tm_5a6b7c8d",
    "tm_9e0f1a2b"
  ],
}
FieldTypeRequiredDescription
idsstring[]YesArray of trademark IDs (prefixed). Max 100.

​
Response

The response preserves the order of your input IDs. Each item in the data array includes a status field indicating whether that individual fetch succeeded: 
{
  "object": "list",
  "data": [
    {
      "id": "tm_7d4e1f2a",
      "object": "trademark",
      "status": "success",
      "data": {
        "id": "tm_7d4e1f2a",
        "object": "trademark",
        "mark_text": "SIGNA",
        "office_code": "uspto",
        "status": { "primary": "active", "stage": "registered" },
        "filing_date": "2024-01-15",
        "nice_classes": [9, 42]
      }
    },
    {
      "id": "tm_3b8c9d0e",
      "object": "trademark",
      "status": "success",
      "data": { ... }
    },
    {
      "id": "tm_5a6b7c8d",
      "object": "trademark",
      "status": "error",
      "error": {
        "type": "https://api.signa.so/errors/not_found",
        "detail": "Trademark tm_5a6b7c8d not found"
      }
    },
    {
      "id": "tm_9e0f1a2b",
      "object": "trademark",
      "status": "success",
      "data": { ... }
    }
  ],
  "request_id": "req_abc123"
}
A batch request returns HTTP 200 even if some individual items fail. Always check the status field on each item in the data array.

​
Batch Sizing

Keep batch sizes at or below 100 items. Requests with more than 100 IDs are rejected with a 400 validation error.
The batch endpoint always returns detail-tier data. Optimal batch sizes depend on the number of records:
Batch SizeApproximate Response Size
20~200 KB
50~500 KB
100~1—2 MB
For large batches, smaller chunks complete faster and use less memory. If you need all 100 records, consider making two requests of 50.

​
Chunking Large Sets

When you have more than 100 IDs, split them into chunks and process sequentially or with controlled concurrency: 
import { Signa } from '@signa-so/sdk';

const signa = new Signa({ api_key: 'sig_live_YOUR_KEY' });

function chunk<T>(array: T[], size: number): T[][] {
  const chunks: T[][] = [];
  for (let i = 0; i < array.length; i += size) {
    chunks.push(array.slice(i, i + size));
  }
  return chunks;
}

async function fetchAllTrademarks(ids: string[]) {
  const chunks = chunk(ids, 100);
  const results = [];

  for (const batch of chunks) {
    const response = await signa.trademarks.batch({ ids: batch });

    for (const item of response.data) {
      if (item.status === 'success') {
        results.push(item.data);
      }
    }
  }

  return results;
}

​
Error Handling in Batches

Individual items in a batch can fail independently. Common per-item errors:
Error TypeMeaningAction
not_foundThe ID does not exist in your organization’s data.Verify the ID. It may have been deleted or belongs to another org.
goneThe entity was merged into another record.Use the merged_into_id to fetch the canonical record.
internal_errorTransient server-side failure for this item.Retry just the failed IDs in a subsequent batch request.
const response = await signa.trademarks.batch({ ids: allIds });

const succeeded: Trademark[] = [];
const notFound: string[] = [];
const retryable: string[] = [];

for (const item of response.data) {
  switch (item.status) {
    case 'success':
      succeeded.push(item.data);
      break;
    case 'error':
      if (item.error.type === 'not_found' || item.error.type === 'gone') {
        notFound.push(item.id);
      } else {
        retryable.push(item.id);
      }
      break;
  }
}

// Retry transient failures
if (retryable.length > 0) {
  const retryResponse = await signa.trademarks.batch({ ids: retryable });
  // ... process retry results
}

​
Performance Tips

If you only need mark text and status for a dashboard, use the list endpoint (GET /v1/trademarks) which returns summary-tier data. Use the batch endpoint when you need the full detail record.
If you have 1,000 IDs to fetch, you can run up to 3 batch requests in parallel without hitting rate limits. Avoid unbounded concurrency, which can trigger 429 responses.
Before making a batch request, check your local cache for IDs you already have. Only send uncached IDs in the batch, then merge the results. This reduces payload size and rate limit usage.
Instead of re-fetching entire batches on a schedule, subscribe to trademark.updated events and only re-fetch the IDs that changed. See the webhooks guide for setup.