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

# Read the newest content-free GPU profile capture of the active revision behind an endpoint



## OpenAPI

````yaml /openapi.json get /api/v1/endpoints/{name}/gpu-profile
openapi: 3.1.0
info:
  description: >-
    Durable, authenticated control-plane operations. Mutation responses may
    outlive the requesting client.
  title: InferCrane Control API
  version: 1.0.0
servers:
  - description: Local InferCrane API and gateway
    url: http://127.0.0.1:18000
security: []
tags:
  - name: Admission
  - name: Adoption
  - name: Agents
  - name: Alerts
  - name: Async inference
  - name: Audit
  - name: Autopilot
  - name: Benchmarks
  - name: Billing
  - name: Billing administration
  - name: Burst Guard
  - name: Capacity intelligence
  - name: Compute
  - name: Context Passport
  - name: Deployments
  - name: Diagnostics
  - name: Endpoints
  - name: External capacity
  - name: FinOps
  - name: Identity
  - name: Inference
  - name: Inference Lab
  - name: Inference decisions
  - name: Inference optimization
  - name: Infrastructure
  - name: Marketplace administration
  - name: Model API administration
  - name: Model APIs
  - name: Model artifacts
  - name: Model catalog
  - name: Monitoring
  - name: Notifications
  - name: Operations
  - name: Planning
  - name: Providers
  - name: Recipes
  - name: Release Guard
  - name: Release evidence
  - name: Replay
  - name: Revisions
  - name: Routing
  - name: Sandboxes
  - name: Scaling
  - name: Secrets
  - name: System
  - name: Targets
  - name: Training lineage
paths:
  /api/v1/endpoints/{name}/gpu-profile:
    get:
      tags:
        - Monitoring
      summary: >-
        Read the newest content-free GPU profile capture of the active revision
        behind an endpoint
      operationId: getEndpointGPUProfile
      parameters:
        - in: path
          name: name
          required: true
          schema:
            minLength: 1
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GPUProfile'
          description: Success
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Typed API error
      security:
        - bearerAuth: []
components:
  schemas:
    GPUProfile:
      additionalProperties: false
      properties:
        analysis:
          $ref: '#/components/schemas/GPUProfileAnalysis'
          description: Required in v2, absent in v1.
        capture:
          additionalProperties: false
          properties:
            accelerator:
              maxLength: 128
              minLength: 1
              type:
                - string
                - 'null'
            content_recorded:
              const: false
              type: boolean
            ended_at:
              format: date-time
              type: string
            evidence_class:
              const: measured
              type: string
            gpus:
              maximum: 1024
              minimum: 1
              type:
                - integer
                - 'null'
            id:
              pattern: ^gpc-[0-9a-f]{32}$
              type: string
            started_at:
              format: date-time
              type: string
            tool:
              description: Capture tool, for example cupti-pc-sampling.
              pattern: ^[a-z][a-z0-9._-]{0,63}$
              type: string
            tool_version:
              pattern: ^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$
              type: string
          required:
            - id
            - tool
            - tool_version
            - evidence_class
            - accelerator
            - gpus
            - started_at
            - ended_at
            - content_recorded
          type: object
        deployment:
          description: The deployment whose active revision was profiled.
          type: string
        endpoint:
          type: string
        frames:
          items:
            $ref: '#/components/schemas/GPUProfileFrame'
          maxItems: 20000
          minItems: 1
          type: array
        recorded_at:
          format: date-time
          type: string
        revision:
          minimum: 1
          type: integer
        schema_version:
          description: >-
            v1 carries call stacks only; v2 adds the trace analysis and an
            optional timeline excerpt.
          enum:
            - infercrane.gpu-profile/v1
            - infercrane.gpu-profile/v2
          type: string
        stacks:
          items:
            $ref: '#/components/schemas/GPUProfileStack'
          maxItems: 10000
          minItems: 1
          type: array
        timeline:
          $ref: '#/components/schemas/GPUProfileTimeline'
        timeline_excerpt:
          $ref: '#/components/schemas/GPUTimelineExcerpt'
          description: 'v2 only: the busiest part of the capture for a timeline viewer.'
        unavailable_layers:
          description: >-
            Layers this capture could not record, for example sass and stall
            without PC sampling.
          items:
            enum:
              - python
              - torch
              - native
              - cuda_api
              - kernel
              - sass
              - stall
            type: string
          maxItems: 7
          type: array
          uniqueItems: true
      required:
        - schema_version
        - endpoint
        - deployment
        - revision
        - capture
        - timeline
        - frames
        - stacks
        - unavailable_layers
        - recorded_at
      type: object
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      type: object
    GPUProfileAnalysis:
      additionalProperties: false
      description: >-
        gpu-trace-analysis-v1: where GPU time goes in one capture. Shares are
        0..1; null is unknown and the section's reason says why.
      properties:
        algorithm_version:
          const: gpu-trace-analysis-v1
          type: string
        categories:
          items:
            additionalProperties: false
            properties:
              category:
                enum:
                  - attention
                  - gemm
                  - communication
                  - memory
                  - norm
                  - activation
                  - sampling
                  - other
                type: string
              count:
                minimum: 0
                type: integer
              kernel_ms:
                minimum: 0
                type: number
              share:
                maximum: 1
                minimum: 0
                type: number
            required:
              - category
              - count
              - kernel_ms
              - share
            type: object
          maxItems: 8
          type: array
        findings:
          items:
            additionalProperties: false
            properties:
              comparison:
                enum:
                  - '>='
                  - <=
                  - '>'
                  - <
                type: string
              observed:
                type: number
              rule:
                type: string
              sentence:
                type: string
              threshold:
                type: number
              unit:
                type: string
            required:
              - comparison
              - observed
              - rule
              - sentence
              - threshold
              - unit
            type: object
          maxItems: 32
          type: array
        hardware:
          oneOf:
            - type: 'null'
            - additionalProperties: false
              properties:
                interval_ms:
                  minimum: 0
                  type: number
                series:
                  items:
                    additionalProperties: false
                    properties:
                      field:
                        type: string
                      unit:
                        type: string
                      values:
                        items:
                          minimum: 0
                          type:
                            - number
                            - 'null'
                        maxItems: 600
                        type: array
                    required:
                      - field
                      - unit
                      - values
                    type: object
                  maxItems: 8
                  type: array
                source:
                  const: dcgm-exporter
                  type: string
              required:
                - interval_ms
                - series
                - source
              type: object
        idle:
          additionalProperties: false
          properties:
            bubbles:
              additionalProperties: false
              properties:
                count:
                  minimum: 0
                  type: integer
                max_us:
                  minimum: 0
                  type:
                    - number
                    - 'null'
                p50_us:
                  minimum: 0
                  type:
                    - number
                    - 'null'
                p95_us:
                  minimum: 0
                  type:
                    - number
                    - 'null'
                top:
                  items:
                    additionalProperties: false
                    properties:
                      cause:
                        enum:
                          - host_wait
                          - launch_gap
                          - other
                        type: string
                      device:
                        minimum: 0
                        type: integer
                      duration_us:
                        minimum: 0
                        type: number
                      start_ms:
                        minimum: 0
                        type: number
                    required:
                      - cause
                      - device
                      - duration_us
                      - start_ms
                    type: object
                  maxItems: 10
                  type: array
              required:
                - count
                - max_us
                - p50_us
                - p95_us
                - top
              type: object
            host_wait_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            idle_ms:
              minimum: 0
              type: number
            launch_gap_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            other_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            reason:
              type: string
          required:
            - bubbles
            - host_wait_share
            - idle_ms
            - launch_gap_share
            - other_share
            - reason
          type: object
        launch:
          additionalProperties: false
          properties:
            graph_launches:
              minimum: 0
              type: integer
            host_launch_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            launch_delay_p50_us:
              minimum: 0
              type:
                - number
                - 'null'
            launch_delay_p95_us:
              minimum: 0
              type:
                - number
                - 'null'
            launches:
              minimum: 0
              type: integer
            per_second:
              minimum: 0
              type: number
            reason:
              type: string
            short_kernel_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
          required:
            - graph_launches
            - host_launch_share
            - launch_delay_p50_us
            - launch_delay_p95_us
            - launches
            - per_second
            - reason
            - short_kernel_share
          type: object
        overlap:
          additionalProperties: false
          properties:
            communication_ms:
              minimum: 0
              type: number
            overlapped_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            reason:
              type: string
          required:
            - communication_ms
            - overlapped_share
            - reason
          type: object
        phases:
          additionalProperties: false
          properties:
            decode:
              additionalProperties: false
              properties:
                gpu_ms:
                  minimum: 0
                  type: number
                share:
                  maximum: 1
                  minimum: 0
                  type: number
                steps:
                  minimum: 0
                  type: integer
              required:
                - gpu_ms
                - share
                - steps
              type: object
            mixed:
              additionalProperties: false
              properties:
                gpu_ms:
                  minimum: 0
                  type: number
                share:
                  maximum: 1
                  minimum: 0
                  type: number
                steps:
                  minimum: 0
                  type: integer
              required:
                - gpu_ms
                - share
                - steps
              type: object
            prefill:
              additionalProperties: false
              properties:
                gpu_ms:
                  minimum: 0
                  type: number
                share:
                  maximum: 1
                  minimum: 0
                  type: number
                steps:
                  minimum: 0
                  type: integer
              required:
                - gpu_ms
                - share
                - steps
              type: object
            source:
              enum:
                - annotations
                - kernel_names
                - unknown
              type: string
            unknown:
              additionalProperties: false
              properties:
                gpu_ms:
                  minimum: 0
                  type: number
                share:
                  maximum: 1
                  minimum: 0
                  type: number
                steps:
                  minimum: 0
                  type: integer
              required:
                - gpu_ms
                - share
                - steps
              type: object
          required:
            - decode
            - mixed
            - prefill
            - source
            - unknown
          type: object
        roofline:
          additionalProperties: false
          properties:
            accelerator:
              type:
                - string
                - 'null'
            covered_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            memory_bound_share:
              maximum: 1
              minimum: 0
              type:
                - number
                - 'null'
            peak:
              oneOf:
                - type: 'null'
                - additionalProperties: false
                  properties:
                    compute_tflops:
                      minimum: 0
                      type: number
                    memory_tbps:
                      minimum: 0
                      type: number
                    precision:
                      type: string
                    source:
                      description: Vendor datasheet the peak comes from, or operator.
                      type: string
                  required:
                    - compute_tflops
                    - memory_tbps
                    - precision
                    - source
                  type: object
            points:
              items:
                additionalProperties: false
                properties:
                  achieved_tflops:
                    minimum: 0
                    type: number
                  bound:
                    enum:
                      - memory
                      - compute
                    type: string
                  bytes:
                    minimum: 0
                    type: number
                  category:
                    enum:
                      - attention
                      - gemm
                      - communication
                      - memory
                      - norm
                      - activation
                      - sampling
                      - other
                    type: string
                  flops:
                    minimum: 0
                    type: number
                  intensity:
                    minimum: 0
                    type: number
                  kernel_ms:
                    minimum: 0
                    type: number
                  label:
                    type: string
                required:
                  - achieved_tflops
                  - bound
                  - bytes
                  - category
                  - flops
                  - intensity
                  - kernel_ms
                  - label
                type: object
              maxItems: 50
              type: array
            position:
              enum:
                - memory_bound
                - compute_bound
                - unknown
              type: string
            reason:
              type: string
            ridge_flop_per_byte:
              minimum: 0
              type:
                - number
                - 'null'
          required:
            - accelerator
            - covered_share
            - memory_bound_share
            - peak
            - points
            - position
            - reason
            - ridge_flop_per_byte
          type: object
        steps:
          additionalProperties: false
          properties:
            count:
              minimum: 0
              type: integer
            items:
              items:
                additionalProperties: false
                properties:
                  duration_ms:
                    minimum: 0
                    type: number
                  gpu_busy_ms:
                    minimum: 0
                    type: number
                  kernels:
                    minimum: 0
                    type: integer
                  phase:
                    enum:
                      - prefill
                      - decode
                      - mixed
                      - unknown
                    type: string
                  start_ms:
                    minimum: 0
                    type: number
                required:
                  - duration_ms
                  - gpu_busy_ms
                  - kernels
                  - phase
                  - start_ms
                type: object
              maxItems: 1000
              type: array
            marker:
              type:
                - string
                - 'null'
            p50_ms:
              minimum: 0
              type:
                - number
                - 'null'
            p95_ms:
              minimum: 0
              type:
                - number
                - 'null'
            reason:
              type: string
            source:
              enum:
                - annotations
                - idle_gaps
                - none
              type: string
          required:
            - count
            - items
            - marker
            - p50_ms
            - p95_ms
            - reason
            - source
          type: object
        top_kernels:
          items:
            additionalProperties: false
            properties:
              category:
                enum:
                  - attention
                  - gemm
                  - communication
                  - memory
                  - norm
                  - activation
                  - sampling
                  - other
                type: string
              count:
                minimum: 0
                type: integer
              max_us:
                minimum: 0
                type: number
              mean_us:
                minimum: 0
                type: number
              name:
                type: string
              phase:
                type:
                  - string
                  - 'null'
              share:
                maximum: 1
                minimum: 0
                type: number
              total_ms:
                minimum: 0
                type: number
            required:
              - category
              - count
              - max_us
              - mean_us
              - name
              - phase
              - share
              - total_ms
            type: object
          maxItems: 25
          type: array
        trace:
          additionalProperties: false
          properties:
            cpu_ops_recorded:
              type: boolean
            devices:
              minimum: 1
              type: integer
            engine:
              enum:
                - vllm
                - sglang
                - null
              type:
                - string
                - 'null'
            engine_version:
              type:
                - string
                - 'null'
            format:
              enum:
                - kineto
                - rocprofv3
                - nsys
              type: string
            kernels:
              minimum: 1
              type: integer
            launches_recorded:
              type: boolean
            shapes_recorded:
              type: boolean
            streams:
              minimum: 1
              type: integer
            truncated:
              description: The trace held more events than one analysis reads.
              type: boolean
            window_ms:
              minimum: 0
              type: number
          required:
            - cpu_ops_recorded
            - devices
            - engine
            - engine_version
            - format
            - kernels
            - launches_recorded
            - shapes_recorded
            - streams
            - truncated
            - window_ms
          type: object
        utilization:
          additionalProperties: false
          properties:
            bucket_ms:
              minimum: 0
              type: number
            busy_series:
              items:
                maximum: 1
                minimum: 0
                type: number
              maxItems: 600
              type: array
            busy_share:
              maximum: 1
              minimum: 0
              type: number
            compute_share:
              maximum: 1
              minimum: 0
              type: number
            idle_share:
              maximum: 1
              minimum: 0
              type: number
            non_compute_share:
              maximum: 1
              minimum: 0
              type: number
          required:
            - bucket_ms
            - busy_series
            - busy_share
            - compute_share
            - idle_share
            - non_compute_share
          type: object
        verdict:
          additionalProperties: false
          properties:
            bottleneck:
              enum:
                - host-launch
                - communication
                - memory-bandwidth
                - compute
                - attention
                - busy
                - unknown
              type: string
            evidence:
              description: The measured values the sentence rests on.
              maxLength: 400
              type: string
            sentence:
              maxLength: 280
              minLength: 1
              type: string
          required:
            - bottleneck
            - evidence
            - sentence
          type: object
      required:
        - algorithm_version
        - categories
        - findings
        - hardware
        - idle
        - launch
        - overlap
        - phases
        - roofline
        - steps
        - top_kernels
        - trace
        - utilization
        - verdict
      type: object
    GPUProfileFrame:
      additionalProperties: false
      properties:
        file:
          maxLength: 512
          type: string
        kind:
          enum:
            - python
            - torch
            - native
            - cuda_api
            - kernel
            - sass
            - stall
          type: string
        line:
          minimum: 1
          type: integer
        name:
          maxLength: 512
          minLength: 1
          type: string
      required:
        - kind
        - name
      type: object
    GPUProfileStack:
      additionalProperties: false
      properties:
        frames:
          description: Root-first indexes into frames.
          items:
            minimum: 0
            type: integer
          maxItems: 128
          minItems: 1
          type: array
        gpu_ns:
          description: GPU time attributed to exactly this stack.
          minimum: 1
          type: integer
      required:
        - frames
        - gpu_ns
      type: object
    GPUProfileTimeline:
      additionalProperties: false
      properties:
        bucket_seconds:
          maximum: 3600
          minimum: 1
          type: integer
        buckets:
          items:
            additionalProperties: false
            properties:
              gpu_seconds:
                description: Null when the bucket has no samples, never zero.
                minimum: 0
                type:
                  - number
                  - 'null'
              start:
                format: date-time
                type: string
            required:
              - start
              - gpu_seconds
            type: object
          maxItems: 500
          type: array
      required:
        - bucket_seconds
        - buckets
      type: object
    GPUTimelineExcerpt:
      additionalProperties: false
      properties:
        categories:
          items:
            enum:
              - attention
              - gemm
              - communication
              - memory
              - norm
              - activation
              - sampling
              - other
              - launch
            type: string
          maxItems: 4000
          type: array
        duration_ms:
          maximum: 2000
          minimum: 0
          type: number
        events:
          description: '[lane, name, start_us, duration_us], start relative to the excerpt.'
          items:
            items:
              minimum: 0
              type: number
            maxItems: 4
            minItems: 4
            type: array
          maxItems: 20000
          type: array
        lanes:
          items:
            additionalProperties: false
            properties:
              device:
                type:
                  - integer
                  - 'null'
              kind:
                enum:
                  - gpu
                  - host
                type: string
              label:
                type: string
              stream:
                type:
                  - integer
                  - 'null'
            required:
              - device
              - kind
              - label
              - stream
            type: object
          maxItems: 128
          type: array
        names:
          items:
            type: string
          maxItems: 4000
          type: array
        start_ms:
          minimum: 0
          type: number
        steps:
          items:
            additionalProperties: false
            properties:
              duration_us:
                minimum: 0
                type: number
              phase:
                enum:
                  - prefill
                  - decode
                  - mixed
                  - unknown
                type: string
              start_us:
                minimum: 0
                type: number
            required:
              - duration_us
              - phase
              - start_us
            type: object
          maxItems: 2000
          type: array
        truncated:
          type: boolean
      required:
        - categories
        - duration_ms
        - events
        - lanes
        - names
        - start_ms
        - steps
        - truncated
      type: object
    Error:
      properties:
        category:
          type: string
        code:
          type: string
        message:
          type: string
        remediation:
          type: string
        request_id:
          type: string
        retryable:
          type: boolean
      required:
        - code
        - message
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.