Query

The Portfolio Query API returns portfolio analytics (values, returns, allocations) grouped and filtered by any combination of Addepar attributes. Unlike the Portfolio Views endpoint (which executes a saved view), Portfolio Query lets you define columns, groupings, and filters dynamically in each request. This makes it the primary endpoint for integrations that need flexible, programmatic access to portfolio data.

The response is a hierarchical tree: a total node containing children grouped by your specified attributes, with column values computed at each level.

Overview

📘

Access requirements

Portfolio query access must be enabled for your API user or application.

Required parameters

Alternative to portfolio_id: Pass external_ids to scope by external identifier. Format: [{"external_type_key": "salesforce", "external_id": "sf_123"}]. See External Identifiers.

Optional parameters

Query portfolio data

POST /v1/portfolio/query

curl -X POST "https://{firm}.addepar.com/api/v1/portfolio/query" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "portfolio_query",
    "attributes": {
      "columns": [
        {"key": "value"},
        {"key": "time_weighted_return"}
      ],
      "groupings": [
        {"key": "asset_class"}
      ],
      "portfolio_type": "ENTITY",
      "portfolio_id": [329263],
      "start_date": "2024-01-01",
      "end_date": "2024-06-30"
    }
  }
}'

{
  "meta": {
    "columns": [
      { "key": "value", "display_name": "Value (USD)", "output_type": "Number", "currency": "USD" },
      { "key": "time_weighted_return", "display_name": "TWR (USD)", "output_type": "Percent", "currency": "USD" }
    ],
    "groupings": [
      { "key": "asset_class", "display_name": "Asset Class" }
    ]
  },
  "data": {
    "type": "portfolio_views",
    "attributes": {
      "total": {
        "name": "Total",
        "columns": { "value": 4.371024413999725E8, "time_weighted_return": 0.023992155163590434 },
        "children": [
          {
            "name": "Equity",
            "grouping": "asset_class",
            "columns": { "value": 2.5993525600627503E8, "time_weighted_return": 0.09047133778274707 },
            "children": []
          },
          {
            "name": "Fixed Income",
            "grouping": "asset_class",
            "columns": { "value": 4.555629874790781E7, "time_weighted_return": 5.433985661802421E-4 },
            "children": []
          }
        ]
      }
    }
  },
  "included": []
}

Response structure:

• meta.columns confirms which columns were computed, with display names and output types.
• meta.groupings confirms the grouping hierarchy.
• data.attributes.total is the root node with portfolio-level totals.
• children arrays contain grouped breakdowns. Each child has name, grouping (which attribute it groups by), columns (computed values), and its own children (for nested groupings).
• Entity-backed groupings (like holding_account) include an entity_id field.
• null column values indicate the calculation is not applicable for that row.

Response codes:

• 200 OK -- Success
• 400 Bad Request -- Invalid query, unsupported attribute, or missing permissions for market data attributes
• 403 Forbidden -- Insufficient permissions or scope

Filter object

Filters narrow results by attribute value before computation.

Discrete filter fields:

Number filter fields (range):

Number filter fields (rank):

Filter example:

"filters": [
  {
    "attribute": "asset_class",
    "type": "discrete",
    "operator": "include",
    "values": ["Equity", "Fixed Income"]
  },
  {
    "attribute": {"key": "value"},
    "type": "number",
    "operator": "rank",
    "rank_order": "top",
    "rank_value": 10
  }
]

Date filters are not supported on Portfolio Query.

Column arguments

Columns accept optional arguments that modify the calculation. The most common argument is adjusted (for adjusted value) and time-based arguments that control the observation window.

"columns": [
  { "key": "value", "arguments": { "adjusted": true } },
  { "key": "time_weighted_return", "arguments": { "period": "trailing P5Y" } }
]

See Attributes to discover available attribute keys and their supported arguments.

Time arguments

Time arguments control when or over what period a calculation is observed. There are two categories: time points (a single moment) and time periods (a span).

Time point arguments

Used with point-in-time attributes like value.

Time period arguments

Used with period attributes like time_weighted_return.

Interval and rounding values

Intervals: D (days), K (weekdays), W (weeks), M (months), Q (quarters), Y (years).

Rounding: floor (start of period), exact (precise date), ceiling (end of period).

Unsupported attributes

The following attributes cannot be used in Portfolio Query requests:

• Allocation Deviation
• Allocation Deviation (%)
• Benchmark
• Benchmark (Rollup)
• Target Allocation
• Target Allocation Range

📘

Related

• Portfolio Views -- Execute a saved analysis view (no dynamic columns)
• Portfolio Query Builder -- Convert an analysis view into a query request body
• Addepar Attributes -- Discover column and grouping keys
• External Identifiers -- Use external IDs as portfolio scope
• Positions -- The ownership data that portfolio queries aggregate
• Rate Limiting -- Portfolio queries are computationally expensive; plan rate budget