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

# Get an owned or public sample

> Resolve an org-owned sample id first, returning its curated detail and inference-job history. Otherwise resolve the same path value as a currently-public share UUID and return only public-safe detail.

Returns an owned sample with its current and historical inference jobs, or a public sample when the path id is a public share UUID. The required `ownership` field discriminates the two response shapes.


## OpenAPI

````yaml GET /samples/{id}
openapi: 3.1.0
info:
  title: Strand AI Platform API
  version: v1
  description: >-
    REST surface for uploading WSIs, submitting Lattice inference jobs, and
    streaming results. All endpoints require an API key or Strand AI OAuth
    access token in the `Authorization: Bearer` header.
servers:
  - url: https://app.strandai.com/api/v1
    description: Production
security:
  - ApiKey: []
  - OAuth2: []
paths:
  /samples/{id}:
    get:
      summary: Get an owned or public sample
      description: >-
        Resolve an org-owned sample id first, returning its curated detail and
        inference-job history. Otherwise resolve the same path value as a
        currently-public share UUID and return only public-safe detail.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Owned or public sample detail
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OwnedSampleDetail'
                  - $ref: '#/components/schemas/PublicSampleDetail'
                discriminator:
                  propertyName: ownership
                  mapping:
                    mine:
                      $ref: '#/components/schemas/OwnedSampleDetail'
                    public:
                      $ref: '#/components/schemas/PublicSampleDetail'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Sample not found in this org
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OwnedSampleDetail:
      type: object
      additionalProperties: false
      description: >-
        An owned sample's curated read model and its 50 newest inference jobs.
        `jobCount` is the uncapped total.
      required:
        - ownership
        - id
        - name
        - filename
        - status
        - fileSize
        - widthPx
        - heightPx
        - mpp
        - tags
        - createdAt
        - expiresAt
        - expiresAtSource
        - expiresInDays
        - willExpire
        - trashedAt
        - jobs
        - jobCount
        - segmentation
      properties:
        ownership:
          type: string
          enum:
            - mine
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
          description: >-
            Human-friendly display name, or null if unset (falls back to
            filename).
        filename:
          type: string
          description: Original uploaded filename.
        status:
          type: string
          description: >-
            Lifecycle status: `uploading`, `upload_failed`, `deid_running`,
            `deid_failed`, `preprocessing`, `ready`, or `preprocess_failed`.
        fileSize:
          type: string
          description: Uploaded file size in bytes (string-encoded 64-bit integer).
        widthPx:
          type: integer
          nullable: true
          description: >-
            Level-0 width in pixels, or null before the dimensions probe
            completes.
        heightPx:
          type: integer
          nullable: true
          description: >-
            Level-0 height in pixels, or null before the dimensions probe
            completes.
        mpp:
          type: number
          nullable: true
          description: >-
            Effective isotropic microns per pixel (user override → calibrated
            slide value), or null when the sample has no usable scale yet.
        tags:
          type: array
          items:
            type: string
          description: The sample's canonical tag strings, sorted alphabetically.
        createdAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: When the sample moves to Trash. Null when it never expires.
        expiresAtSource:
          type: string
          nullable: true
          enum:
            - org_default
            - custom
            - null
          description: >-
            `org_default` = derived from the org policy at upload time. `custom`
            = set by an explicit expiration call (a date or a never-expire pin).
            Null when the sample has no expiration and no org policy applies.
        expiresInDays:
          type: integer
          nullable: true
          description: >-
            Whole days until expiry, clamped at 0 for a sample at/past its date
            but not yet swept. Null when the sample never expires.
        willExpire:
          type: boolean
          description: True when the sample has an expiration date set.
        trashedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the sample entered Trash, or null if it is still active.
            Trashed samples are permanently deleted 7 days after this time.
        jobs:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/SampleJob'
        jobCount:
          type: integer
          minimum: 0
          description: Total inference-job count for the sample before the 50-job cap.
        segmentation:
          $ref: '#/components/schemas/SegmentationState'
    PublicSampleDetail:
      type: object
      additionalProperties: false
      description: >-
        A public sample's curated detail. `id` is the public share UUID; the
        internal sample identity and job history are never exposed.
      required:
        - ownership
        - id
        - title
        - thumbnailUrl
        - tags
        - metadata
        - geometry
        - viewer
      properties:
        ownership:
          type: string
          enum:
            - public
        id:
          type: string
          format: uuid
        title:
          type: string
        thumbnailUrl:
          type: string
          description: v1-relative path to the sample's JPEG thumbnail.
        tags:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        geometry:
          type: object
          required:
            - widthPx
            - heightPx
            - mppX
            - mppY
          description: Level-0 pixel dimensions and microns-per-pixel of the H&E image.
          properties:
            widthPx:
              type: integer
            heightPx:
              type: integer
            mppX:
              type: number
              nullable: true
            mppY:
              type: number
              nullable: true
        viewer:
          type: object
          required:
            - pyramidUrl
            - markers
          description: >-
            How to read the pixel data: the OME-Zarr pyramid base path and the
            marker channels it carries.
          properties:
            pyramidUrl:
              type: string
              description: >-
                v1-relative base path of the OME-Zarr store (`GET
                /public/samples/{publicId}/zarr/{...path}`). The root manifest
                is `{pyramidUrl}/zarr.json`.
            markers:
              type: array
              description: Live marker channels available in the pyramid.
              items:
                type: object
                required:
                  - name
                properties:
                  name:
                    type: string
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
        required:
          type: integer
          nullable: true
        retryAfterSeconds:
          type: integer
          nullable: true
    SampleJob:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - progress
        - reservedCredits
        - markers
        - createdAt
        - startedAt
        - completedAt
        - errorMessage
        - resultsAvailable
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: >-
            Lifecycle: `queued` → `dispatching` → `preprocessing` → `running` →
            `postprocessing` → terminal. Terminal values: `completed`,
            `partial_failed`, `failed`, and `cancelled`.
        progress:
          type: number
          nullable: true
        reservedCredits:
          type: integer
          nullable: true
        markers:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          nullable: true
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        errorMessage:
          type: string
          nullable: true
        resultsAvailable:
          type: boolean
    SegmentationState:
      type: object
      additionalProperties: false
      required:
        - status
        - retryable
        - creditCost
        - job
        - layer
      properties:
        status:
          type: string
          enum:
            - not_started
            - queued
            - running
            - postprocessing
            - completed
            - failed
            - cancelled
        retryable:
          type: boolean
        creditCost:
          type: integer
          enum:
            - 0
          description: Segmentation is credit-free.
        job:
          type: object
          nullable: true
          additionalProperties: true
        layer:
          type: object
          nullable: true
          additionalProperties: true
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: sk-strand-XXXXXXXXXXXXXXXXXXXXXXXX
    OAuth2:
      type: oauth2
      description: >-
        Strand AI authorization-code flow with S256 PKCE, explicit organization
        consent, and RFC 8707 resource binding.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.strandai.com/oauth2/auth
          tokenUrl: https://auth.strandai.com/oauth2/token
          scopes:
            samples:read: Read slide metadata and estimates
            samples:write: Upload and change slides
            jobs:read: Read run status
            jobs:write: Start, export, or cancel runs
            results:read: Read and download results
            credits:spend: Reserve and spend organization credits

````