> ## 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 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, statements, 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 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/PositionEarnings' description: OK '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 PositionEarnings: properties: cost_basis: description: Total acquisition cost of the position. examples: - '2000.00' title: Cost Basis type: string currency: allOf: - $ref: '#/components/schemas/Currency' description: Currency of the earnings amounts. gross_capital: description: Capital earnings before fees and taxes. examples: - '175.00' title: Gross Capital type: string gross_income: description: Income earnings before fees and taxes. examples: - '34.75' title: Gross Income type: string gross_realized: description: Realized earnings before fees and taxes. examples: - '125.50' title: Gross Realized type: string gross_total: description: Total realized and unrealized gross earnings. examples: - '209.75' title: Gross Total type: string gross_unrealized: description: Unrealized earnings before fees and taxes. examples: - '84.25' title: Gross Unrealized type: string gross_unrealized_percentage: description: Unrealized gross earnings as a proportion of cost basis. examples: - '0.0421' title: Gross Unrealized Percentage 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 realized_capital: description: Realized earnings from capital appreciation. examples: - '100.00' title: Realized Capital type: string realized_income: description: Realized earnings from income. examples: - '25.50' title: Realized Income type: string unrealized_capital: description: Unrealized earnings from capital appreciation. examples: - '75.00' title: Unrealized Capital type: string unrealized_income: description: Unrealized earnings from income. examples: - '9.25' title: Unrealized Income type: string required: - position - gross_realized - gross_unrealized - gross_total - gross_capital - gross_income - gross_unrealized_percentage - realized_capital - realized_income - unrealized_capital - unrealized_income - cost_basis - currency - period_start - period_end title: PositionEarnings 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 Currency: enum: - EUR - USD - GBP properties: {} title: Currency type: string 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 securitySchemes: HTTPBearer: scheme: bearer type: http ````