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

# Test Execute Tool

Run a tool's [execution body](/features/tool-registry/auto-execution) in the sandbox against test inputs. This is what the editor's **Test Run** button calls behind the scenes; useful for verifying a body works as expected before promoting the version.

## Resolving the version

Without `label` or `version` query params, the latest version is used. Pass `label=production` to test the production version, or `version=3` to pin to a specific number.

## In-flight overrides

Both `execution` and `tool_definition` in the body are **optional overrides**. If you supply them, they take precedence over what's stored on the version. This lets you test changes without saving a new version first.

## Result shape

The endpoint returns `200` for both successful runs and user-code errors. Inspect `result.status`:

* `"success"` → your body returned a value, available at `result.result`
* `"error"` → your body raised, with details under `result.error.message`

Sandbox infrastructure failures (sandbox unreachable, internal errors) return `502`. These are operational issues, not your code's fault.


## OpenAPI

````yaml POST /api/public/v2/tool-registry/{identifier}/test-execute
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /api/public/v2/tool-registry/{identifier}/test-execute:
    post:
      tags:
        - tool-registry
      summary: Test Execute Tool
      operationId: test_execute_tool
      parameters:
        - required: true
          schema:
            type: string
            title: X-Api-Key
          name: X-API-KEY
          in: header
        - name: identifier
          in: path
          required: true
          schema:
            type: string
            description: Tool ID (numeric) or name
        - name: label
          in: query
          required: false
          schema:
            type: string
            description: >-
              Resolve version by label name (e.g. production). Falls back to
              latest if neither label nor version supplied.
        - name: version
          in: query
          required: false
          schema:
            type: string
            description: Resolve by specific version number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                inputs:
                  type: object
                  description: >-
                    Arguments passed to the tool body. Same shape the LLM would
                    emit — keys match the tool's parameter names.
                  additionalProperties: true
                execution:
                  type: object
                  description: >-
                    In-flight override of the stored execution config. Lets you
                    test unsaved code.
                  nullable: true
                  required:
                    - type
                    - language
                    - code
                  properties:
                    type:
                      type: string
                      enum:
                        - code
                    language:
                      type: string
                      enum:
                        - python
                        - javascript
                    code:
                      type: string
                tool_definition:
                  type: object
                  description: >-
                    In-flight override of the stored tool definition. Used to
                    test against a different function name without saving.
                  nullable: true
      responses:
        '200':
          description: >-
            Tool executed (success or user-code error). User-code errors return
            status="error" inside the result object — they do NOT raise.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  result:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - success
                          - error
                      result:
                        description: >-
                          The tool body's return value (any JSON-serializable
                          type). Present on status="success".
                        nullable: true
                      stdout:
                        type: string
                      stderr:
                        type: string
                      duration_ms:
                        type: integer
                      error:
                        type: object
                        nullable: true
                        description: >-
                          Present on status="error". Includes `type` and
                          `message`.
        '400':
          description: Missing execution config or function name
        '404':
          description: Tool or version not found
        '502':
          description: Sandbox infrastructure failure
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````