> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noonum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Backtest a portfolio of companies

> Accepts a list of company IDs with weights, resolves each to a tradeable security, fetches historical price data, and computes a buy-and-hold NAV series and statistics over the requested period.



## OpenAPI

````yaml /api-reference/openapi.json post /backtest
openapi: 3.0.0
info:
  title: Noonum API
  version: 1.0.0
  contact:
    name: Noonum Support
    email: hello@noonum.com
  description: >
    Create, read, update, and delete your own investment strategies, browse
    public premade strategies, run semantic search, and call supporting utility
    endpoints.
servers:
  - url: https://api.noonum.ai/v1
security:
  - bearerAuth: []
tags:
  - name: UserStrategies
    description: Create, read, update, and delete your own investment strategies.
  - name: PremadeStrategies
    description: Read public premade strategies and find the ones closest to an objective.
  - name: Helper
    description: >-
      Supporting endpoints for company lookup, objective editing, and health
      checks.
  - name: Benchmarks
    description: Read benchmark data.
  - name: Portfolios
    description: Create, read, update, and delete your portfolios.
  - name: Backtest
    description: Backtest a portfolio without saving it.
paths:
  /backtest:
    post:
      tags:
        - Backtest
      summary: Backtest a portfolio of companies
      description: >-
        Accepts a list of company IDs with weights, resolves each to a tradeable
        security, fetches historical price data, and computes a buy-and-hold NAV
        series and statistics over the requested period.
      operationId: app.api.v1.backtest.backtest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - holdings
              properties:
                holdings:
                  type: array
                  description: The companies to backtest, each with a portfolio weight.
                  items:
                    type: object
                    required:
                      - companyId
                      - weight
                    properties:
                      companyId:
                        type: string
                        format: uuid
                        description: Company (issuer) ID in the Noonum database.
                      weight:
                        type: number
                        description: The company's weight in the portfolio.
                        example: 0.5
                years:
                  type: integer
                  description: Number of years to backtest over.
                  default: 5
                  minimum: 1
                  maximum: 20
                benchmark:
                  type: string
                  default: SPY
                  description: >-
                    Benchmark symbol to compare against, for example `SPY` or
                    `QQQ`.
      responses:
        '200':
          description: Backtest results
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    description: Performance statistics for the portfolio.
                    properties:
                      returns:
                        type: number
                        description: Total cumulative return over the backtest period.
                        example: 0.7955
                      annualizedReturn:
                        type: number
                        description: Compound annual growth rate (CAGR).
                        example: 0.1242
                      variance:
                        type: number
                        description: Annualized volatility.
                        example: 0.1637
                      sharpeRatio:
                        type: number
                        description: Sharpe ratio over the backtest period.
                        example: 0.76
                      maxDrawdown:
                        type: number
                        description: Largest peak-to-trough decline over the period.
                        example: -0.2747
                      stockCount:
                        type: integer
                        description: >-
                          Number of companies that resolved to a tradeable
                          security.
                        example: 20
                      weekCount:
                        type: integer
                        description: Number of weekly data points in the series.
                        example: 260
                      warnings:
                        type: array
                        description: >-
                          Messages about companies that could not be resolved or
                          priced.
                        items:
                          type: string
                  timeSeries:
                    type: array
                    description: >-
                      Portfolio NAV points, each given as `[unix_seconds, nav]`,
                      starting at 10000.
                    items:
                      type: array
                      items:
                        type: number
                    example:
                      - - 1594339200
                        - 10000
                      - - 1594944000
                        - 10156.8
                  benchmarkMetadata:
                    type: object
                    description: Performance statistics for the benchmark.
                    properties:
                      symbol:
                        type: string
                        description: The benchmark symbol these statistics are for.
                        example: SPY
                      returns:
                        type: number
                        example: 0.6512
                      annualizedReturn:
                        type: number
                        example: 0.1058
                      variance:
                        type: number
                        example: 0.1423
                      sharpeRatio:
                        type: number
                        example: 0.74
                      maxDrawdown:
                        type: number
                        example: -0.2385
                  benchmarkTimeSeries:
                    type: array
                    description: >-
                      Benchmark price series rebased to 10000 and aligned to the
                      portfolio dates.
                    items:
                      type: array
                      items:
                        type: number
                    example:
                      - - 1594339200
                        - 10000
                      - - 1594944000
                        - 10089.5
        '400':
          description: >-
            No holdings could be resolved to securities, or price history was
            insufficient to run the backtest.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or API Key
      description: |
        Enter 'Bearer' followed by a space and then your JWT or API Key.
        Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
        or `Bearer YOUR_API_KEY_HERE`

````