> ## 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-v2.json post /backtest
openapi: 3.0.0
info:
  title: Noonum API v2
  version: 2.0.0
  contact:
    name: Noonum Support
    email: hello@noonum.com
  description: >
    Create and manage investment strategies, portfolios, and backtests. The API
    covers the full strategy lifecycle, including creation and editing, the
    archive and revive flow, version submission and run state, result companies,
    evidence, factsheets, exposures, and taxonomy.
servers:
  - url: https://api.noonum.ai/v2
security:
  - bearerAuth: []
tags:
  - name: UserStrategies
    description: Create, read, update, and manage your own investment strategies.
  - name: Helper
    description: >-
      Shared utilities for company lookup and search, objective tooling, and a
      health check.
  - name: Portfolios
    description: Create, read, update, and delete portfolios.
  - name: Backtest
    description: Run a standalone backtest on a portfolio of companies.
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.v2.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`

````