alpaca-mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

get_portfolio_history

Retrieve account equity and profit/loss data over a chosen time window to track performance and analyze trading results.

Instructions

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

Input Schema

Name	Required	Description	Default
`end`	No	The 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.
`start`	No	The 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.
`period`	No	The 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_reset`	No	`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
`timeframe`	No	The resolution of time window. 1Min, 5Min, 15Min, 1H, or 1D. If omitted, 1Min for less than 7 days period, 15Min for less than 30 days, or otherwise 1D. For queries with longer than 30 days of `period`, the system only accepts 1D as `timeframe`.
`cashflow_types`	No	The cashflow activities to include in the report. One of 'ALL', 'NONE', or a comma-separated list of activity types.
`extended_hours`	No	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_reporting`	No	For 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

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv2.4.0Oct 17, 2026

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"
```

Addedv2.0.0Apr 15, 2026

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden, yet it only says data is retrieved. It omits that all parameters are optional, that omitted start/end are defaulted by complex session/market rules, that extended_hours is deprecated, or anything about pagination or response size. A read-only retrieval is implied but nothing beyond that is disclosed.

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 no filler and the resource named before the scope. It is efficient, though so terse that it borders on under-specification for an 8-parameter tool.

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?

The rich input schema and the presence of an output schema mean the description needn't re-explain parameters or return values, so this is roughly minimum viable. However, with no annotations and a deprecated parameter and intricate defaulting rules, the description gives the agent no high-level warning about defaults or deprecation.

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 schema already documents the semantics of all 8 parameters in depth. The description adds only the loose phrase 'requested time window,' which gestures at start/end/period without adding meaning beyond the schema. Baseline 3 is appropriate.

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?

The description states a specific verb (Retrieves) and resource (account portfolio history, with equity and P/L named) scoped to a time window, so the agent knows exactly what it returns. It does not distinguish itself from siblings such as get_account_activities or get_account_info, which also return account-level data, so it falls short of a 5.

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

Usage Guidelines2/5

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

There is no statement of when to use this tool versus alternatives (e.g., get_account_activities for cashflows) and no mention of prerequisites, such as needing an authenticated account. Usage is only inferable from the name, which is the definition of no explicit guidance.

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

Deploy Server