> ## Documentation Index > Fetch the complete documentation index at: https://docs.engine.usesophic.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve position earnings (P&L) > Retrieve a position's earnings (P&L) for the requested period. Note the period supports full date-times, with timezone information. ## OpenAPI ````yaml /openapi.json get /positions/{position_id}/earnings openapi: 3.1.0 info: title: Sophic Engine API version: 0.1.0 servers: - url: https://api.engine.usesophic.com security: [] tags: - description: Retrieve accounts and account documents. name: accounts x-group: Accounts - description: Read the audit trail of platform activity. name: activity x-group: Activity - description: Obtain OAuth access tokens for the Engine API. name: auth x-group: Authentication - description: Inspect the authenticated user or service actor. name: identity x-group: Identity - description: Retrieve fee schedules and billing information. name: billing x-group: Billing - description: Browse instruments and tradable products. name: catalog x-group: Catalog - description: Track onboarding applications through completion. name: onboarding x-group: Onboarding - description: Manage customer records and related person data. name: customers x-group: Customers - description: List platform events and inspect individual occurrences. name: events x-group: Events - description: Read positions, transactions, and account holdings. name: holdings x-group: Holdings - description: Retrieve legal agreements and required disclosures. name: legal-documents x-group: Legal Documents - description: Access prices and market data for instruments. name: market-data x-group: Market Data - description: Manage deposits, withdrawals, and funding accounts. name: payments x-group: Payments - description: Retrieve returns, earnings, and performance metrics. name: performance x-group: Performance - description: Place and manage orders, quotes, and trades. name: trading x-group: Trading - description: Read position and account valuations over time. name: valuation x-group: Valuation - description: Configure webhook endpoints and inspect deliveries. name: webhooks x-group: Webhooks - description: Upload files and retrieve stored documents. name: files x-group: Files paths: /positions/{position_id}/earnings: get: tags: - performance summary: Retrieve position earnings (P&L) description: >- Retrieve a position's earnings (P&L) for the requested period. Note the period supports full date-times, with timezone information. operationId: get_position_earnings_positions__position_id__earnings_get parameters: - in: path name: position_id required: true schema: title: Position Id type: string - description: >- Predefined period over which earnings are computed. Takes precedence over `period_start`/`period_end` when provided. in: query name: period required: false schema: anyOf: - $ref: '#/components/schemas/Period' - type: 'null' description: >- Predefined period over which earnings are computed. Takes precedence over `period_start`/`period_end` when provided. title: Period - description: >- The period start (in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format). If omitted, it defaults to the position opening date/time. Note that the period is interpreted as a half-open interval with `period_start` included and `period_end` excluded. in: query name: period_start required: false schema: description: >- The period start (in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format). If omitted, it defaults to the position opening date/time. Note that the period is interpreted as a half-open interval with `period_start` included and `period_end` excluded. examples: - period_start=2025-11-12T00:00:00Z - period_start=2025-11-12 format: date-time title: Period Start type: string x-remove-null-from-type-union: true - description: >- The period end (in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format). If omitted, it defaults to the current date/time. Note the period is interpreted as a half-open interval with `period_start` included and `period_end` excluded. in: query name: period_end required: false schema: description: >- The period end (in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format). If omitted, it defaults to the current date/time. Note the period is interpreted as a half-open interval with `period_start` included and `period_end` excluded. examples: - period_end=2025-11-12T00:00:00Z - period_end=2025-11-12 format: date-time title: Period End type: string x-remove-null-from-type-union: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PositionEarningsV2' description: Successful Response '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request security: - HTTPBearer: [] components: schemas: Period: enum: - 1d - 1w - 1m - this-month - 3m - 6m - ytd - 1y - all properties: {} title: Period type: string PositionEarningsV2: properties: account: description: ID of the account holding the position. title: Account type: string period_end: description: End date and time of the earnings period. examples: - '2026-03-31T23:59:59Z' format: date-time title: Period End type: string period_start: description: Start date and time of the earnings period. examples: - '2026-01-01T00:00:00Z' format: date-time title: Period Start type: string position: description: ID of the position the earnings were computed for. title: Position type: string reporting: allOf: - $ref: '#/components/schemas/PositionReportingEarnings' description: >- The position's earnings in the account's base currency, with a breakdown into what the investment earned and what exchange-rate movements added or took away. Summed over all positions, these give the account's positions figures. trading: allOf: - $ref: '#/components/schemas/PositionTradingEarnings' description: The position's earnings in the instrument's own currency. required: - position - account - period_start - period_end - trading - reporting title: PositionEarningsV2 type: object Error: properties: code: description: A machine-readable error code. title: Code type: string context: additionalProperties: anyOf: - type: string - type: integer description: An optional object for adding extra context to the error. title: Context type: object x-remove-null-from-type-union: true detail: description: A human-readable description of the error. title: Detail type: string docs: description: A URL to documentation about this error code. title: Docs type: string x-remove-null-from-type-union: true params: description: An optional list of params that failed validation. items: $ref: '#/components/schemas/InvalidParam' title: Params type: array x-remove-null-from-type-union: true required: - detail - code title: Error type: object PositionReportingEarnings: properties: attribution: allOf: - $ref: '#/components/schemas/EarningsAttribution' description: >- Breakdown of the earnings into how much came from the investment itself and how much from exchange-rate movements. cost_basis: description: >- Acquisition cost of the units still held, converted at the exchange rates in force when they were bought. title: Cost Basis type: string currency: allOf: - $ref: '#/components/schemas/Currency' description: The account's base currency. gross: description: >- Total earnings before fees in the account's currency, each part converted at the exchange rate of the day it happened. Equals the investment effect plus the currency effect. title: Gross type: string required: - currency - cost_basis - gross - attribution title: PositionReportingEarnings type: object PositionTradingEarnings: properties: attribution: allOf: - $ref: '#/components/schemas/TradingEarningsAttribution' description: >- Breakdown of the earnings into realized and unrealized, and within each into price changes and income. cost_basis: description: Total acquisition cost of the units still held. title: Cost Basis type: string currency: allOf: - $ref: '#/components/schemas/Currency' description: The instrument's currency. gross: description: Total realized and unrealized earnings before fees and taxes. title: Gross type: string unrealized_percentage: description: Unrealized earnings as a proportion of the cost basis. title: Unrealized Percentage type: string required: - currency - cost_basis - gross - unrealized_percentage - attribution title: PositionTradingEarnings type: object InvalidParam: properties: code: description: A machine-readable error code. title: Code type: string detail: description: Human-readable detail for error. title: Detail type: string path: description: Path to the field name (or index if a list) that errored. items: anyOf: - type: integer - type: string title: Path type: array required: - path - detail - code title: InvalidParam type: object EarningsAttribution: properties: currency: allOf: - $ref: '#/components/schemas/EarningsEffect' description: >- How much came from exchange-rate movements on the money invested in positions, between the day it was invested and either the day it was sold or today. Zero when everything is in the account's currency. investment: allOf: - $ref: '#/components/schemas/EarningsEffect' description: >- How much came from the investments themselves, that is price changes and income, with the effect of exchange-rate movements stripped out. required: - investment - currency title: EarningsAttribution type: object Currency: enum: - EUR - USD - GBP properties: {} title: Currency type: string TradingEarningsAttribution: properties: investment: allOf: - $ref: '#/components/schemas/EarningsEffect' description: >- How much the position earned, measured in the instrument's own currency. Exchange rates play no part here, so there is no currency effect. required: - investment title: TradingEarningsAttribution type: object EarningsEffect: properties: realized: allOf: - $ref: '#/components/schemas/RealizedEarningsSplit' description: >- Earnings already locked in: from units sold and income paid out, each converted at the exchange rate of the day it happened. total: description: Realized plus unrealized. title: Total type: string unrealized: allOf: - $ref: '#/components/schemas/UnrealizedEarningsSplit' description: >- Earnings not yet locked in: from units still held and interest accrued but not yet paid, converted at the current exchange rate. required: - total - realized - unrealized title: EarningsEffect type: object RealizedEarningsSplit: properties: capital: description: The part that came from price changes on units sold. title: Capital type: string income: description: The part that came from income paid out. title: Income type: string required: - capital - income title: RealizedEarningsSplit type: object UnrealizedEarningsSplit: properties: capital: description: The part that came from price changes on units still held. title: Capital type: string income: description: The part that came from interest accrued but not yet paid. title: Income type: string required: - capital - income title: UnrealizedEarningsSplit type: object securitySchemes: HTTPBearer: scheme: bearer type: http ````