Skip to main content
Glama
alpaca-mcp-server

alpaca-mcp-server

Official
by alpacahq

get_portfolio_history

Retrieve account equity and profit/loss history over a requested time window to analyze portfolio performance.

Instructions

Retrieves account portfolio history (equity and P/L) over a requested time window.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get_portfolio_history"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoThe last timestamp of the timeseries. Defaults to `start + period` when `start` is provided. When `start` and `end` are omitted, or if `end` is AFTER the request time, `end` defaults to - The most recent session open timestamp if `intraday_reporting=extended_hours` - The most recent market open timestamp if `intraday_reporting=market_hours` - The current timestamp if `intraday_reporting=continuous` `end` may be combined with `start` or `period`, but cannot be combined with both.
startNoThe first timestamp of the timeseries. Defaults to `end - period`. When `timeframe=1D`, if `start` occurs any time on a trading day (including outside of market hours), `start` is set to the closing time of the current trading day. Otherwise, `start` is rolled forward to the closing time of the next available trading day. When `timeframe != 1D`, one of the following rules is applied. - When `intraday_reporting=continuous`, `start` is rolled back to the nearest `timeframe` interval. - When both `start` and `end` are omitted, `start` is rolled back to the first market/session open that is encountered. - When `intraday_reporting != continuous` and `start` is a trading day: - roll forward to the first market/session open if `start` is outside of market/session hours, or - roll back to the nearest `timeframe` interval if `start` occurs during trading hours. - Roll forward to the next market/session open if `start` does not fall on a trading day. `start` may be combined with `end` or `period`, but cannot be combined with both.
periodNoThe total duration of history being requested defined as `number` + `unit`. Valid units are: `D`, `W`, `M`, and `A` (annum). The following restrictions apply: - MUST NOT be included if both `start` and `end` are provided. - Default value is `1M` when `start` or `end` is omitted.
pnl_resetNo`pnl_reset` defines how we are calculating the baseline values for Profit And Loss (pnl) for queries with `timeframe` less than 1D (intraday queries). The default behavior for intraday queries is that we reset the pnl value to the previous day's closing equity for each **trading** day. In case of crypto (given its continuous nature), this might not be desired: specifying "no_reset" disables this behavior and all pnl values returned will be relative to the closing equity of the previous trading day. For 1D resolution all PnL values are calculated relative to the `base_value`, we are not resetting the base value. per_day
timeframeNoAn interval, duration, or window of time.
cashflow_typesNoThe cashflow activities to include in the report. One of 'ALL', 'NONE', or a comma-separated list of activity types.
extended_hoursNo**deprecated**: Users are strongly advised to **rely on the `intraday_reporting` query parameter** for better control of the reporting range. If true, include extended hours in the result. This is effective only for timeframe less than 1D.
intraday_reportingNoFor intraday resolutions (<1D) this specifies which timestamps to return data points for: Allowed values are: - **market_hours** Only timestamps for the core equity trading hours are returned (usually 9:30am to 4:00pm, trading days only). - **extended_hours** Returns timestamps for the whole session including extended hours (usually 4:00am to 8:00pm, trading days only). - **continuous** Returns price data points 24/7 (for off-session times too). To calculate the equity values we are using the following prices: Between 4:00am and 10:00pm on trading days the valuation will be calculated based on the last trade (extended hours and normal hours respectively). After 10:00pm, until the next session open the equities will be valued at their official closing price on the primary exchange. market_hours

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.4.1
    • changedInput schema / properties / timeframe / description
      Previous value: -"The resolution of time window. 1Min, 5Min, 15Min, 1H, or 1D. If omitted, 1Min for less than 7 days period,\n15Min for less than 30 days, or otherwise 1D.\n\nFor queries with longer than 30 days of `period`, the system only accepts 1D as `timeframe`.\n"New value: +"An interval, duration, or window of time."
    • addedInput schema / properties / timeframe / enum
      Added value: +[
      +  "1D",
      +  "1H",
      +  "15Min",
      +  "5Min",
      +  "1Min"
      +]
    • addedInput schema / properties / timeframe / example
      Added value: +"15Min"
  2. Changed11 schema fields changedv2.4.0
    • changedInput schema / properties / end / description
      Previous value: -"The timestamp the data is returned up to in RFC3339 format (including timezone specification). Defaults to the current time.\n\nIf provided, the `end` value is always normalized to the `America/New_York` timezone and adjusted to the nearest `timeframe` interval, e.g. seconds are always truncated and the time is rounded backwards to the nearest interval of `1Min`, `5Min`, `15Min`, or `1H`.\n\nWhen `intraday_reporting` is either `market_hours` or `extended_hours`, the `end` value is adjusted to not occur after session close on the specified day. For example if the `intraday_reporting` is `extended_hours`, and the timestamp specified is `2023-10-19T21:33:00-04:00`, `end` is adjusted to `2023-10-19T20:00:00-04:00`.\n\n`end` may be combined with `start` or `period`.\n\nProviding all of `start`, `end`, and `period` is invalid.\n"New value: +"The last timestamp of the timeseries.\n\nDefaults to `start + period` when `start` is provided.\n\nWhen `start` and `end` are omitted, or if `end` is AFTER the request time, `end` defaults to\n- The most recent session open timestamp if `intraday_reporting=extended_hours`\n- The most recent market open timestamp if `intraday_reporting=market_hours`\n- The current timestamp if `intraday_reporting=continuous`\n\n`end` may be combined with `start` or `period`, but cannot be combined with both.\n"
    • removedInput schema / properties / end / example
      Removed value: -"2021-03-16T18:38:01Z"
    • addedInput schema / properties / end / examples
      Added value: +[
      +  "2021-03-16T18:38:01Z",
      +  "2021-03-16T18:38:01-04:00",
      +  "2021-03-16"
      +]
    • removedInput schema / properties / end / format
      Removed value: -"date-time"
    • changedInput schema / properties / intraday_reporting / description
      Previous value: -"For intraday resolutions (<1D) this specifies which timestamps to return data points for:\n\nAllowed values are:\n- **market_hours**\n\n  Only timestamps for the core equity trading hours are returned (usually 9:30am to 4:00pm, trading days only)\n\n- **extended_hours**\n\n  Returns timestamps for the whole session including extended hours (usually 4:00am to 8:00pm, trading days only)\n\n- **continuous**\n\n  Returns price data points 24/7 (for off-session times too). To calculate the equity values we are using the following prices:\n\n  Between 4:00am and 10:00pm on trading days the valuation will be calculated based on the last trade (extended hours and normal hours respectively).\n\n  After 10:00pm, until the next session open the equities will be valued at their official closing price on the primary exchange.\n"New value: +"For intraday resolutions (<1D) this specifies which timestamps to return data points for:\n\nAllowed values are:\n- **market_hours**\n\n  Only timestamps for the core equity trading hours are returned (usually 9:30am to 4:00pm, trading days only).\n\n- **extended_hours**\n\n  Returns timestamps for the whole session including extended hours (usually 4:00am to 8:00pm, trading days only).\n\n- **continuous**\n\n  Returns price data points 24/7 (for off-session times too). To calculate the equity values we are using the following prices:\n\n  Between 4:00am and 10:00pm on trading days the valuation will be calculated based on the last trade (extended hours and normal hours respectively).\n\n  After 10:00pm, until the next session open the equities will be valued at their official closing price on the primary exchange.\n"
    • changedInput schema / properties / period / description
      Previous value: -"The duration of the data in `number` + `unit` format, such as 1D, where `unit` can be D for day, W for week, M for month and A for year. Defaults to 1M.\n\nOnly two of `start`, `end` and `period` can be specified at the same time.\n\nFor intraday timeframes (\\<1D) only 30 days or less can be queried, for 1D resolutions there is no such limit, data is available since the\ncreation of the account.\n"New value: +"The total duration of history being requested defined as `number` + `unit`.\nValid units are: `D`, `W`, `M`, and `A` (annum).\n\nThe following restrictions apply:\n- MUST NOT be included if both `start` and `end` are provided.\n- Default value is `1M` when `start` or `end` is omitted.\n"
    • addedInput schema / properties / period / examples
      Added value: +[
      +  "7D",
      +  "4W",
      +  "1M",
      +  "1A"
      +]
    • changedInput schema / properties / start / description
      Previous value: -"The timestamp the data is returned starting from in RFC3339 format (including timezone specification). Defaults to `end` minus `period`\n\nIf provided, the `start` value is always normalized to the `America/New_York` timezone and adjusted to the nearest `timeframe` interval, e.g. seconds are always truncated and the time is rounded backwards to the nearest interval of `1Min`, `5Min`, `15Min`, or `1H`.\n\nIf `timeframe=1D` and `start` is not a valid trading date, find the next available trading date. For example, if `start` occurs on Saturday or Sunday after converting to the America/New_York timezone, `start` is adjusted to the first weekday that is not a market holiday (e.g. Monday).\n\nIf `timeframe` is less than `1D` and `intraday_reporting` is not `continuous`, `start` always reflects the beginning of a market session. If `start` is between midnight and the end (inclusive) of an active trading day, `start` is set to the beginning of the session on the specified day. Otherwise, if `start` occurs outside of the market session, the next available market date is used.\n\nFor example, when `intraday_reporting=market_hours` and `start=2023-10-19T23:59:59-04:00`, the provided `start` date occurs outside of the regular market session. The effective `start` timestamp is adjusted to the beginning of the next session: `2023-10-20T09:30:00-04:00`\n\n`start` may be be combined with one of `end` or `period`.\n\nProviding all of `start`, `end`, and `period` is invalid.\n"New value: +"The first timestamp of the timeseries.\n\nDefaults to `end - period`.\n\nWhen `timeframe=1D`, if `start` occurs any time on a trading day (including outside of market hours), `start` is set to the closing time of the current trading day. Otherwise, `start` is rolled forward to the closing time of the next available trading day.\n\nWhen `timeframe != 1D`, one of the following rules is applied.\n- When `intraday_reporting=continuous`, `start` is rolled back to the nearest `timeframe` interval.\n- When both `start` and `end` are omitted, `start` is rolled back to the first market/session open that is encountered.\n- When `intraday_reporting != continuous` and `start` is a trading day:\n  - roll forward to the first market/session open if `start` is outside of market/session hours, or\n  - roll back to the nearest `timeframe` interval if `start` occurs during trading hours.\n- Roll forward to the next market/session open if `start` does not fall on a trading day.\n\n`start` may be combined with `end` or `period`, but cannot be combined with both.\n"
    • removedInput schema / properties / start / example
      Removed value: -"2021-03-16T18:38:01Z"
    • addedInput schema / properties / start / examples
      Added value: +[
      +  "2021-03-16T18:38:01Z",
      +  "2021-03-16T18:38:01-04:00",
      +  "2021-03-16"
      +]
    • removedInput schema / properties / start / format
      Removed value: -"date-time"
  3. Addedv2.0.0

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing beyond 'read retrieval'. It omits that all parameters are optional and that period defaults to 1M, that start/end/period are mutually constrained, and that pnl_reset and intraday_reporting materially change the returned values — all of which live only in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler, which is efficient. It is arguably too terse for a tool with eight interacting date parameters, but nothing is wasted or buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the schema documents the date-window rules thoroughly. Still, for a tool whose correctness hinges on mutually exclusive start/end/period combinations and a deprecated parameter, a one-clause description leaves the agent to reconstruct the calling contract entirely from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds only the phrase 'requested time window', which gestures at start/end/period but gives no semantics for the eight parameters, including the non-obvious pnl_reset and the deprecated extended_hours flag.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Retrieves account portfolio history') and clarifies the payload (equity and P/L) plus the time-window scoping. That is enough to separate it from the market-data siblings like get_stock_bars or get_portfolio_history's neighbors, though it never explicitly names a sibling it supersedes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'account portfolio history' signals this is for the user's own account rather than market data, but there is no explicit when-to-use, no prerequisites (auth/account scope), and no mention of alternatives for intraday vs historical needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools