openapi: 3.1.0
info:
  title: Pixie Clusters Scripts API
  description: The Pixie API provides programmatic access to the Pixie Kubernetes observability platform. It enables listing and managing clusters, executing PxL scripts to query telemetry data collected via eBPF, and retrieving results including full-body application requests, resource metrics, and network data without requiring manual instrumentation.
  version: '0.1'
  contact:
    name: Pixie Community
    url: https://px.dev/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://work.withpixie.ai
  description: Pixie Cloud API server
security:
- apiKeyAuth: []
tags:
- name: Scripts
  description: Operations for executing PxL scripts against a cluster and retrieving telemetry query results.
paths:
  /api/pxl/execute:
    post:
      operationId: executeScript
      summary: Pixie Execute a PxL script
      description: Executes a PxL script on a specified cluster and returns the telemetry query results as structured tabular data. PxL scripts use a Python-based domain-specific language to query eBPF-collected data including HTTP requests, resource metrics, network flows, and application traces.
      tags:
      - Scripts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteScriptRequest'
      responses:
        '200':
          description: Script execution results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteScriptResponse'
        '400':
          description: Invalid script or request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Cluster not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Script execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ColumnData:
      type: object
      description: Data values for a single column in a row batch.
      properties:
        stringData:
          type: object
          description: String-typed column values.
          properties:
            data:
              type: array
              items:
                type: string
        int64Data:
          type: object
          description: Int64-typed column values.
          properties:
            data:
              type: array
              items:
                type: integer
                format: int64
        float64Data:
          type: object
          description: Float64-typed column values.
          properties:
            data:
              type: array
              items:
                type: number
                format: double
        booleanData:
          type: object
          description: Boolean-typed column values.
          properties:
            data:
              type: array
              items:
                type: boolean
        uint128Data:
          type: object
          description: UInt128-typed column values (used for UUIDs and IP addresses).
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  high:
                    type: integer
                    format: int64
                  low:
                    type: integer
                    format: int64
    ScriptStatus:
      type: object
      description: Status of a script execution.
      properties:
        code:
          type: integer
          description: Status code. 0 indicates success; non-zero values indicate errors.
        message:
          type: string
          description: Human-readable status message or error description.
        errorDetails:
          type: array
          description: Detailed error information if the script encountered errors.
          items:
            type: object
            properties:
              compilerError:
                type: object
                description: Compilation error detail for PxL scripts.
                properties:
                  line:
                    type: integer
                    description: Line number where the error occurred.
                  column:
                    type: integer
                    description: Column number where the error occurred.
                  message:
                    type: string
                    description: Error message.
    ExecuteScriptResponse:
      type: object
      description: Response containing the results of a PxL script execution.
      properties:
        status:
          $ref: '#/components/schemas/ScriptStatus'
        tables:
          type: array
          description: Tabular result sets returned by the script. Each table corresponds to a px.display() call in the PxL script.
          items:
            $ref: '#/components/schemas/ResultTable'
    Relation:
      type: object
      description: Schema describing the columns of a result table.
      properties:
        columns:
          type: array
          description: Column definitions for the result table.
          items:
            $ref: '#/components/schemas/Column'
    Column:
      type: object
      description: A column definition in a result table.
      properties:
        columnName:
          type: string
          description: Name of the column.
        columnType:
          type: string
          description: Data type of the column.
          enum:
          - BOOLEAN
          - INT64
          - UINT128
          - FLOAT64
          - STRING
          - TIME64NS
          - DURATION64NS
          - JSONOBJECT
          - UNKNOWN
        columnDesc:
          type: string
          description: Human-readable description of the column's contents.
        columnSemanticType:
          type: string
          description: Semantic type hint for rendering and interpretation, such as ST_HTTP_RESP_STATUS for HTTP status codes.
    ResultTable:
      type: object
      description: A single tabular result set from a PxL script execution.
      properties:
        name:
          type: string
          description: Name of the result table, set by the first argument to px.display().
        relation:
          $ref: '#/components/schemas/Relation'
        data:
          type: array
          description: Rows of data in the result table.
          items:
            $ref: '#/components/schemas/RowBatch'
    ExecuteScriptRequest:
      type: object
      description: Request to execute a PxL script on a target cluster.
      required:
      - cluster_id
      - pxl_script
      properties:
        cluster_id:
          type: string
          format: uuid
          description: Unique identifier of the cluster to run the script against.
        pxl_script:
          type: string
          description: PxL script source code to execute. PxL is a Python-dialect DSL for querying Pixie telemetry data.
          example: 'import px

            df = px.DataFrame(table=''http_events'', start_time=''-5m'')

            px.display(df)'
        func_name:
          type: string
          description: Name of a specific function within the PxL script to invoke. If omitted, the script is executed as a module-level script.
        script_args:
          type: object
          description: Key-value arguments to pass to the PxL script function. Values must be strings.
          additionalProperties:
            type: string
    RowBatch:
      type: object
      description: A batch of rows in a result table.
      properties:
        numRows:
          type: integer
          description: Number of rows in this batch.
        eos:
          type: boolean
          description: If true, this is the last batch for this table.
        cols:
          type: array
          description: Column data arrays in the same order as the relation's columns.
          items:
            $ref: '#/components/schemas/ColumnData'
    ErrorResponse:
      type: object
      description: Standard error response from the Pixie API.
      properties:
        code:
          type: integer
          description: Error code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: array
          description: Additional error details.
          items:
            type: object
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: pixie-api-key
      description: Pixie API key for authenticating requests. Generate an API key from the Pixie Cloud UI under Profile > API Keys.
externalDocs:
  description: Pixie API Documentation
  url: https://docs.px.dev/reference/api/overview/