---
search:
  tags:
    - Portfolio
    - GET
seo:
  description: >-
    Returns one page of settlements for an authorized account. Reference for the
    GET /portfolio/{account_id}/settlements endpoint in the REST API.
sidebar:
  label: Get Settlements
  badge: GET
title: Get Settlements
type: openapi-operation
---
Returns one page of settlements for an authorized account.

### Endpoint

- Method and path: `GET /portfolio/{account_id}/settlements`
- Operation ID: `getSettlements`
- API reference: [GET /portfolio/{account_id}/settlements](/api-reference/rest/portfolio/get-settlements)
- Complete specification: [OpenAPI (YAML)](/openapi.yml)
- Spec location (JSON Pointer): `#/paths/~1portfolio~1{account_id}~1settlements/get`

#### Authorization

- Accepted credentials: `UDX-Access-Key` header and `UDX-Access-Timestamp` header and `UDX-Access-Signature` header; or Bearer token in `Authorization`
- Details: [Authentication](/reference/authentication)

#### Parameters

```yaml
- $ref: "#/components/parameters/VersionHeader"
- name: account_id
  in: path
  required: true
  description: Account whose settlements to return.
  schema:
    $ref: "#/components/schemas/EntityId"
- name: ticker
  in: query
  required: false
  description: Filter by market ticker.
  schema:
    $ref: "#/components/schemas/Ticker"
- name: settled_at_or_after
  in: query
  required: false
  description: Return settlements at or after this instant, compared at millisecond precision.
  schema:
    type: string
    format: date-time
    maxLength: 40
    example: 2026-01-01T00:00:00.000000Z
- name: settled_at_or_before
  in: query
  required: false
  description: Return settlements at or before this instant, compared at millisecond precision.
  schema:
    type: string
    format: date-time
    maxLength: 40
    example: 2026-01-01T00:00:00.000000Z
- name: settled_on_or_after
  in: query
  required: false
  description: Include settlements on or after this settlement business date.
  schema:
    type: string
    format: date
    maxLength: 10
    example: 2026-01-01
- name: settled_on_or_before
  in: query
  required: false
  description: Include settlements on or before this settlement business date.
  schema:
    type: string
    format: date
    maxLength: 10
    example: 2026-01-01
- name: trade_id
  in: query
  required: false
  description: Filter to the exchange-assigned trade identifier associated with the settlement.
  schema:
    type: string
    maxLength: 128
    example: trade-123
- $ref: "#/components/parameters/PaginationLimit"
- $ref: "#/components/parameters/PaginationPage"
- name: order
  in: query
  required: false
  description: Settlement time direction. The relative order of settlements with equal times is unspecified.
  schema:
    type: string
    enum:
      - asc
      - desc
    default: desc
    example: desc
```


#### Responses

##### `200`

A page of settled positions.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/json`

Schema:

```yaml
$ref: "#/components/schemas/SettlementsListResponse"
```

Example: Example

```json
{
  "settlements": [
    {
      "account_id": "6820943174116859281",
      "ticker": "UDX-EXAMPLE-MARKET",
      "quantity": "60",
      "market_result": "yes",
      "settlement_price": "1.00",
      "payout": "60.00",
      "settled_at": "2026-01-01T00:00:00.000000Z"
    }
  ],
  "next_page_url": null
}
```

##### `400`

The request doesn't conform to this spec.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Invalid request parameters

```json
{
  "type": "urn:udx:problem:invalid-request-parameters",
  "title": "Bad Request",
  "status": 400,
  "detail": "invalid request parameters",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

Example: Unknown UDX-Version

```json
{
  "type": "urn:udx:problem:unknown-version",
  "title": "Bad Request",
  "status": 400,
  "detail": "unknown UDX-Version \"1999-01-01\"; supported versions: 2026-07-15",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `401`

No valid credential was provided.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Authentication failed

```json
{
  "type": "urn:udx:problem:invalid-authentication-credentials",
  "title": "Unauthorized",
  "status": 401,
  "detail": "invalid authentication credentials",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `403`

The credential lacks the read scope.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Insufficient permissions

```json
{
  "type": "urn:udx:problem:insufficient-permissions",
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient permissions",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `429`

The member rate limit was exceeded.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
Retry-After:
  $ref: "#/components/headers/RetryAfter"
Cache-Control:
  $ref: "#/components/headers/NoStore"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Example

```json
{
  "type": "urn:udx:problem:member-rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "this member has temporarily exceeded its request rate",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `500`

Something went wrong on UDX's side.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Internal server error

```json
{
  "type": "urn:udx:problem:internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `503`

Request admission or account setup is unavailable, or the read could not be completed in time; retry.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
Retry-After:
  $ref: "#/components/headers/RetryAfter"
Cache-Control:
  $ref: "#/components/headers/NoStore"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Caller setup is not ready

```json
{
  "type": "urn:udx:problem:projection-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "account setup is still being completed; retry later",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

Example: Request admission is unavailable

```json
{
  "type": "urn:udx:problem:request-admission-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "request admission is temporarily unavailable",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

Example: The read could not be completed in time

```json
{
  "type": "urn:udx:problem:could-not-process-retry",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "could not process request, please retry",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```


#### Referenced definitions

The references in the excerpts above resolve to these definitions in the complete specification.

##### `#/components/headers/VersionHeader`

```yaml
description: API version used for this response.
schema:
  type: string
  maxLength: 10
  description: A dated API version (YYYY-MM-DD).
  example: 2026-07-15
```

##### `#/components/schemas/SettlementsListResponse`

```yaml
type: object
description: A page of settled positions.
required:
  - settlements
  - next_page_url
properties:
  settlements:
    type: array
    maxItems: 100
    description: One page of settled positions.
    items:
      $ref: "#/components/schemas/Settlement"
  next_page_url:
    $ref: "#/components/schemas/NextPageURL"
```

##### `#/components/schemas/Settlement`

```yaml
type: object
description: A settlement.
required:
  - account_id
  - ticker
  - quantity
  - market_result
  - settlement_price
  - payout
  - settled_at
properties:
  account_id:
    type: string
    minLength: 1
    description: The account that held the position.
    example: "6820943174116859281"
  ticker:
    $ref: "#/components/schemas/Ticker"
  quantity:
    type: string
    pattern: ^[0-9]+(\.[0-9]{1,2})?$
    maxLength: 24
    description: Net position held at resolution (absolute value), in contracts.
    example: "100"
  market_result:
    $ref: "#/components/schemas/MarketResult"
  settlement_price:
    type: string
    pattern: ^[0-9]+(\.[0-9]{1,6})?$
    maxLength: 24
    description: Per-contract settlement value, in dollars.
    example: "0.55"
  payout:
    type: string
    pattern: ^-?[0-9]+(\.[0-9]{1,6})?$
    maxLength: 25
    description: Signed settlement cash flow for the position, in dollars. Positive is credited to the account; negative is debited.
    example: "-12.50"
  settled_at:
    type: string
    format: date-time
    maxLength: 40
    description: When the position settled.
    example: 2026-01-01T00:00:00.000000Z
```

##### `#/components/schemas/Ticker`

```yaml
type: string
minLength: 1
maxLength: 128
description: A human-meaningful natural key naming a single-leg or multi-leg market.
example: UDX-EXAMPLE-MARKET
```

##### `#/components/schemas/MarketResult`

```yaml
type: string
enum:
  - yes
  - no
  - void
description: A market's settlement outcome. void means the market settled at a partial value rather than YES or NO.
```

##### `#/components/schemas/NextPageURL`

```yaml
type:
  - string
  - "null"
format: uri-reference
maxLength: 4096
pattern: ^/[^/\s#][^\s#]*$
description: Root-relative URL for the next page. Null when there are no more items.
example: /api_keys?limit=10&order=desc&page=eyJ2IjoxLCJzIjoiMjAyNi0wNi0wMVQxMjowMDowMC4wMDAwMDBaIiwiaWQiOiIzNTE3NDU2MjI5NjM0MTg1NjQ2In0&sort=created_at
```

##### `#/components/schemas/ProblemDetails`

```yaml
type: object
description: An RFC 9457 machine-readable error, returned on every non-2xx response. The response's Content-Language header identifies the language used by title and detail, and Vary includes Accept-Language.
required:
  - type
  - title
  - status
properties:
  type:
    type: string
    format: uri-reference
    maxLength: 2048
    description: A stable URN identifying the kind of problem, for example urn:udx:problem:insufficient-permissions. Branch on it rather than on the localized detail. It is an identifier, not a URL to dereference.
  title:
    type: string
    maxLength: 40
    example: Bad Request
    description: A localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
  status:
    type: integer
    example: 400
    description: The HTTP status code, repeated from the response itself.
  detail:
    type: string
    maxLength: 500
    example: malformed request body
    description: A localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
  instance:
    type: string
    format: uri-reference
    maxLength: 100
    example: urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef
    description: An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
```

##### `#/components/headers/RetryAfter`

```yaml
description: Whole seconds to wait before retrying.
schema:
  type: integer
  minimum: 1
  description: A positive delay in whole seconds.
  example: 2
```

##### `#/components/headers/NoStore`

```yaml
description: Prevents caching this response.
schema:
  type: string
  enum:
    - no-store
  description: Always the cache directive no-store.
  example: no-store
```

##### `#/components/parameters/VersionHeader`

```yaml
name: UDX-Version
in: header
required: false
description: Dated API version (YYYY-MM-DD).
schema:
  type: string
  minLength: 10
  maxLength: 10
  description: A dated API version (YYYY-MM-DD).
  example: 2026-07-15
```

##### `#/components/schemas/EntityId`

```yaml
type: string
minLength: 1
description: An exchange-assigned identifier. Treat it as an opaque, stable key with no internal structure.
example: "6820943174116859281"
```

##### `#/components/parameters/PaginationLimit`

```yaml
name: limit
in: query
required: false
description: Maximum number of items to return in one page.
schema:
  type: integer
  minimum: 1
  maximum: 100
  default: 10
  description: Page size.
  example: 10
```

##### `#/components/parameters/PaginationPage`

```yaml
name: page
in: query
required: false
description: Opaque token identifying the requested page.
schema:
  type: string
  maxLength: 512
  description: An opaque pagination cursor.
  example: eyJ2IjoxLCJzIjoiMjAyNi0wNi0wMVQxMjowMDowMC4wMDAwMDBaIiwiaWQiOiIzNTE3NDU2MjI5NjM0MTg1NjQ2In0
```