Filtering Events

Filter the event stream to receive only relevant events.

Query Parameters

The Events API supports filtering via query parameters:

Parameter	Type	Description
types	string	Comma-separated event types
issuers	string	Comma-separated company names or CIKs
since	timestamp	Only events after this time

Filter by Event Type

Receive only specific event types:

// Only Form 4 trades
const source = new EventSource('/api/stream?types=FORM_4');

// Multiple types
const source = new EventSource('/api/stream?types=FORM_4,FILING_8K');

Available types:

• FORM_4 - Insider trades
• FILING_8K - Current reports
• FILING_10K - Annual reports
• FILING_10Q - Quarterly reports
• NEWS - Financial news

Filter by Issuer

Receive events for specific companies:

// By company name
const source = new EventSource('/api/stream?issuers=APPLE%20INC,NVIDIA%20CORP');

// By CIK
const source = new EventSource('/api/stream?issuers=0000320193,0001045810');

Filter by Time

Receive only recent events:

// Events from the last hour
const oneHourAgo = new Date(Date.now() - 3600000).toISOString();
const source = new EventSource(`/api/stream?since=${oneHourAgo}`);

Combine Filters

Combine multiple filters:

const params = new URLSearchParams({
  types: 'FORM_4',
  issuers: '0000320193', // Apple
  since: new Date(Date.now() - 86400000).toISOString(), // Last 24h
});

const source = new EventSource(`/api/stream?${params}`);

Client-Side Filtering

For more complex filtering, process events client-side:

interface Event {
  eventType: string;
  issuer: string;
  metadata?: {
    transactionCode?: string;
    totalValue?: number;
  };
}

function filterEvents(event: Event): boolean {
  // Only purchases over $1M
  if (event.eventType !== 'FORM_4') return false;
  if (event.metadata?.transactionCode !== 'P') return false;
  if ((event.metadata?.totalValue ?? 0) < 1000000) return false;
  return true;
}

source.onmessage = (e) => {
  const event = JSON.parse(e.data);
  if (filterEvents(event)) {
    processEvent(event);
  }
};

Watchlists

Build a watchlist filter:

const watchlist = new Set([
  '0000320193', // Apple
  '0001045810', // NVIDIA
  '0001318605', // Tesla
  '0001652044', // Alphabet
  '0000789019', // Microsoft
]);

source.onmessage = (e) => {
  const event = JSON.parse(e.data);
  if (watchlist.has(event.cik)) {
    alertUser(event);
  }
};

Performance Considerations

• Use server-side filtering (types, issuers) to reduce bandwidth
• Client-side filtering is more flexible but increases data transfer
• For large watchlists (>100 symbols), prefer server-side CIK filtering