Getting Data

Learn how to retrieve accounts, orders, positions, and other data from connected brokerages.

Once the session is initialized and the user has approved read permissions on a broker connection, you can retrieve accounts, orders, and positions with a consistent API shape.

Overview

The most common read methods are:

getAccounts()
getOrders()
getPositions()

Each returns a standard response object. On success, result.success.data contains a PaginatedData collection that you can use like an array.

Get Accounts

Retrieve accounts across connected brokers:

const result = await finatic.getAccounts();

if (result.success) {
  const accounts = result.success.data;
  console.log(`Found ${accounts.length} account(s)`);
} else {
  console.error('Failed to get accounts:', result.error);
}

Account Filters

You can filter accounts with:

brokerId (string, optional): Filter by broker (e.g., 'alpaca', 'tastytrade')
connectionId (string, optional): Filter by connection ID
accountType (string, optional): Filter by account type (broker-specific enum)
status (string, optional): Filter by account status (broker-specific enum)
currency (string, optional): Filter by currency code (e.g., 'USD')
limit (number, optional): Number of results to return
offset (number, optional): Number of results to skip
includeMetadata (boolean, optional): Include additional metadata

const result = await finatic.getAccounts({
  brokerId: 'alpaca',
  accountType: 'margin',
  currency: 'USD'
});

Get Orders

Retrieve orders from connected brokers:

const result = await finatic.getOrders();

if (result.success) {
  const orders = result.success.data;
  console.log(`Found ${orders.length} order(s)`);
} else {
  console.error('Failed to get orders:', result.error);
}

Order Filters

You can filter orders with:

brokerId (string, optional): Filter by broker ID
connectionId (string, optional): Filter by connection ID
accountId (string, optional): Filter by account ID
symbol (string, optional): Filter by symbol (e.g., 'AAPL', 'TSLA')
orderStatus (enum, optional): Filter by status (broker-specific enum)
side (enum, optional): Filter by side ('buy', 'sell')
assetType (enum, optional): Filter by asset type ('equity', 'option', 'future', etc.)
createdAfter (string, optional): ISO 8601 lower bound
createdBefore (string, optional): ISO 8601 upper bound
limit (number, optional): Number of results to return
offset (number, optional): Number of results to skip
includeMetadata (boolean, optional): Include additional metadata

const result = await finatic.getOrders({
  accountId: '123456789',
  symbol: 'AAPL',
  orderStatus: 'filled',
  limit: 50
});

Get Positions

Retrieve positions from connected brokers:

const result = await finatic.getPositions();

if (result.success) {
  const positions = result.success.data;
  console.log(`Found ${positions.length} position(s)`);
} else {
  console.error('Failed to get positions:', result.error);
}

Position Filters

You can filter positions with:

brokerId (string, optional): Filter by broker ID
connectionId (string, optional): Filter by connection ID
accountId (string, optional): Filter by account ID
symbol (string, optional): Filter by symbol (e.g., 'AAPL')
side (enum, optional): Filter by side ('long', 'short')
assetType (enum, optional): Filter by asset type
positionStatus (enum, optional): Filter by position status (broker-specific enum)
updatedAfter (string, optional): ISO 8601 lower bound
updatedBefore (string, optional): ISO 8601 upper bound
limit (number, optional): Number of results to return
offset (number, optional): Number of results to skip
includeMetadata (boolean, optional): Include additional metadata

const result = await finatic.getPositions({
  accountId: '123456789',
  symbol: 'AAPL',
  side: 'long'
});

Pagination

getAccounts(), getOrders(), and getPositions() return paginated data. On success:

result.success.data: PaginatedData collection (array-like)
result.success.data.hasMore: Whether additional pages exist
result.success.data.nextPage(): Fetch the next page
result.success.data.prevPage(): Fetch the previous page
result.success.data.firstPage(): Jump to the first page
result.success.data.lastPage(): Jump to the last page

const result = await finatic.getOrders({ limit: 50 });

if (result.success) {
  const page1 = result.success.data;
  console.log(`Page 1: ${page1.length} order(s)`);

  if (page1.hasMore) {
    const page2 = await page1.nextPage();
    console.log(`Page 2: ${page2.length} order(s)`);

    const page1Again = await page2.prevPage();
    console.log(`Back to page 1: ${page1Again.length} order(s)`);
  }
}

Manual pagination example

const page1 = await finatic.getOrders({ limit: 50, offset: 0 });
const page2 = await finatic.getOrders({ limit: 50, offset: 50 });

Note: Each method also has a "get all" version (getAllAccounts(), getAllOrders(), getAllPositions()) that fetches all pages and returns a single array. Use those methods when you need the full dataset without manual pagination.

Response Format

All methods in this guide return the standard response object. Always check result.success or result.error before reading data:

const result = await finatic.getAccounts();

if (result.success) {
  const accounts = result.success.data;
  // Process accounts
} else if (result.error) {
  console.error('Error:', result.error.message);
  // Handle error
}

For detailed response and error semantics, see:

Standard Response Object - Understand the shared response contract.
Error Handling - Handle failures and edge cases safely.

Next Steps

Now that you've retrieved your data:

Standard Response Object - Understand the response format used by all methods.
Connecting Brokers - Learn how to connect brokerages to access real data.
Error Handling - Review error handling patterns for robust applications.
Explore the API Reference - See all available methods in the API Reference.
Try the Interactive Playground - Test the SDK in your browser with our Interactive Playground.