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

# Create Eval Run

> Manually run evals for a workforce component (no deploy). Defaults to the env worktree so uncommitted evals are included; pass source=git for a clean extract.



## OpenAPI

````yaml POST /orgs/{org_id}/projects/{project_id}/envs/{env_id}/evals/runs
openapi: 3.1.0
info:
  title: Timbal Platform API
  description: Public API documentation for the Timbal platform
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.timbal.ai
    description: Production
  - url: https://api.dev.timbal.ai
    description: Development
security: []
tags:
  - name: ace
    description: Action Control Engine (ACE) operations
  - name: analytics
    description: Org and project analytics
  - name: billing
    description: Subscriptions, usage, and payment-related operations
  - name: content
    description: Re-sign stored content URLs
  - name: files
    description: File operations
  - name: iam
    description: IAM — actions, roles, users, and authorization introspection
  - name: k2
    description: Knowledge Bases v2 operations
  - name: orgs
    description: Organization operations
  - name: projects
    description: Project operations
  - name: runs
    description: Execution operations
  - name: templates
    description: Public project template catalog
  - name: users
    description: Authenticated user profile
paths:
  /orgs/{org_id}/projects/{project_id}/envs/{env_id}/evals/runs:
    post:
      tags:
        - projects
      description: >-
        Manually run evals for a workforce component (no deploy). Defaults to
        the env worktree so uncommitted evals are included; pass source=git for
        a clean extract.
      operationId: handler
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
        - name: project_id
          in: path
          required: true
          schema:
            type: string
        - name: env_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunEvalsReqBody'
        required: true
      responses:
        '202':
          description: Eval run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunEvalsResBody'
        '400':
          description: Missing component filter, bad source/rev combo, or unknown rev
        '403':
          description: Insufficient permissions
        '404':
          description: Component not found (in the project, worktree, or at the rev)
        '422':
          description: Component has no eval files under evals/
      security:
        - bearer_auth: []
components:
  schemas:
    RunEvalsReqBody:
      type: object
      properties:
        component_id:
          type:
            - string
            - 'null'
          description: |-
            Workforce component by numeric app id (the `TIMBAL_APP_ID` value;
            number or string). At least one of `component_id` / `component_uid`
            is required; when both are set, they must resolve to the same
            component.
        component_uid:
          type:
            - string
            - 'null'
          description: Workforce component by manifest uid (the `_id` in `timbal.yaml`).
        rev:
          type:
            - string
            - 'null'
          description: |-
            Git rev to extract when `source = "git"` (branch, tag, or SHA).
            Defaults to the env's tracked branch. Rejected when
            `source = "worktree"`.
        source:
          $ref: '#/components/schemas/EvalRunSource'
          description: |-
            `worktree` (default) or `git`. Worktree includes uncommitted
            evals; git is a clean extract at `rev`.
    RunEvalsResBody:
      type: object
      required:
        - eval_run_id
        - status
      properties:
        eval_run_id:
          type: string
          description: >-
            Id of the created eval run. Stream `GET
            .../evals/runs/{eval_run_id}/events`

            or poll `GET .../evals/runs/{eval_run_id}`.
        status:
          type: string
          description: Always `running` at accept time.
    EvalRunSource:
      type: string
      description: Where to read the component source + eval YAML from for a manual run.
      enum:
        - worktree
        - git
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: >-
        Timbal API key. Obtain your API key from the Timbal platform settings.
        See [Authentication](/api-reference/authentication) for more
        information.

````