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

# Get an Annotation

> Retrieve an [Annotation](/core-resources/annotation) from its `id`.

<Accordion title="Authentication" icon="key">
  Every request sent to Scale's API requires authentication. In short, your API Key is the Bearer token. See the [Authentication](/get-started/authentication) section for more details.
</Accordion>


## OpenAPI

````yaml GET /v2/annotation
openapi: 3.1.0
info:
  title: GenAI API Spec
  description: 'Data Engine: Generative AI API Specification'
  version: 0.0.1
servers:
  - url: https://api.scale.com
security:
  - bearerAuth: []
  - basicAuth: []
paths:
  /v2/annotation:
    get:
      tags:
        - v2
      summary: Get an Annotation
      description: Retrieve an [Annotation](/core-resources/annotation) from its `id`.
      operationId: getAnnotation
      parameters:
        - $ref: '#/components/parameters/annotation_id'
      responses:
        '200':
          description: Completed annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnnotationResponse'
              examples:
                Integer:
                  value:
                    id: an_abc123
                    type: integer
                    key: formatting
                    value: 3
                    title: Response Formatting
                    description: Does the response contain issues with formatting?
                    possible_values:
                      - 1
                      - 2
                      - 3
                    labels:
                      - Major Issues
                      - Minor Issues
                      - No Issues
                Boolean:
                  value:
                    id: an_abc123
                    type: boolean
                    key: rateable
                    value: true
                    title: Is this prompt able to be rated?
                    description: Does it meet the criteria of the project?
                    possible_values:
                      - true
                      - false
                    labels:
                      - 'Yes'
                      - 'No'
                Category:
                  value:
                    id: an_abc123
                    type: category
                    key: selected_model_id
                    value: model_1
                    title: Select the best response
                    description: >-
                      When the responses are fully loaded, select the best
                      response from the options.
                    possible_values:
                      - model_1
                      - model_2
                    labels:
                      - Response 1
                      - Response 2
                Category Multiple:
                  value:
                    id: an_abc123
                    type: category_multiple
                    key: justification_multiple_choice
                    value:
                      - grammar
                      - relevance
                    title: Why was the response you picked better?
                    description: >-
                      Why was the chosen response better than the other? (Select
                      all that apply.)
                    possible_values:
                      - accuracy
                      - grammar
                      - concise
                      - relevance
                    labels:
                      - Response was more accurate
                      - >-
                        Was easier to read (proper spelling, punctuation, and
                        grammar)
                      - Contained less off-topic information
                      - Contained more relevant information to the prompt
                Text:
                  value:
                    id: an_abc123
                    type: text
                    key: justification
                    value: '@Response 1 was better than @Response 2 because ...'
                    title: Select the best response
                    description: >-
                      Please provide a justification. Use "@Response 1" and
                      "@Response 2" to refer to the model responses.
                File:
                  value:
                    id: an_abc123
                    type: file
                    key: expected_image
                    value:
                      url: https://example.com/image.jpg
                      scale_url: https://scale-....com/cdn/xyz123
                      name: image.jpg
                      mime_type: image/jpeg
                    title: Expected Image
                    description: >-
                      Upload a picture of what you expect the model to respond
                      with.
        '500':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status_code:
                    type: number
                    example: 500
                  error:
                    type: string
                    example: An error has occurred.
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: |
            import scaleapi

            API_KEY = 'live_...'
            client = scaleapi.ScaleClient(API_KEY)

            ANNOTATION_ID = 'abc123'
            response = client.v2.get_annotation(ANNOTATION_ID)
            print(response.to_json())
        - lang: python
          label: Python
          source: |
            import requests

            API_KEY = 'live_...'
            ANNOTATION_ID = 'abc123'

            response = requests.request(
              "GET",
              url="https://api.scale.com/v2/annotation",
              params={"annotation_id": ANNOTATION_ID},
              headers={
                "Accept": "application/json",
                "Authorization": f"Bearer {API_KEY}",
              },
            )
            print(response.json())
components:
  parameters:
    annotation_id:
      name: annotation_id
      in: query
      required: true
      description: The unique identifier of the annotation.
      schema:
        $ref: '#/components/schemas/AnnotationId'
  schemas:
    GetAnnotationResponse:
      $ref: '#/components/schemas/Annotation'
    AnnotationId:
      type: string
      description: Unique identifier for an annotation.
      example: overall_quality
    Annotation:
      type: object
      description: Represents a generic annotation.
      required:
        - id
        - key
        - type
      oneOf:
        - $ref: '#/components/schemas/AnnotationInteger'
        - $ref: '#/components/schemas/AnnotationBoolean'
        - $ref: '#/components/schemas/AnnotationText'
        - $ref: '#/components/schemas/AnnotationCategory'
        - $ref: '#/components/schemas/AnnotationCategoryMultiple'
        - $ref: '#/components/schemas/AnnotationFile'
        - $ref: '#/components/schemas/AnnotationWorkspaceContainer'
        - $ref: '#/components/schemas/AnnotationRankedChoices'
        - $ref: '#/components/schemas/AnnotationRankedGroups'
      discriminator:
        propertyName: type
        mapping:
          integer:
            $ref: '#/components/schemas/AnnotationInteger'
          boolean:
            $ref: '#/components/schemas/AnnotationBoolean'
          text:
            $ref: '#/components/schemas/AnnotationText'
          category:
            $ref: '#/components/schemas/AnnotationCategory'
          category_multiple:
            $ref: '#/components/schemas/AnnotationCategoryMultiple'
          file:
            $ref: '#/components/schemas/AnnotationFile'
          workspace_container:
            $ref: '#/components/schemas/AnnotationWorkspaceContainer'
          ranked_choices:
            $ref: '#/components/schemas/AnnotationRankedChoices'
          ranked_groups:
            $ref: '#/components/schemas/AnnotationRankedGroups'
    AnnotationInteger:
      title: Integer
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationIntegerProperties'
    AnnotationBoolean:
      title: Boolean
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationBooleanProperties'
    AnnotationText:
      title: Text
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationTextProperties'
    AnnotationCategory:
      title: Category
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationCategoryProperties'
    AnnotationCategoryMultiple:
      title: Category-Multiple
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationCategoryMultipleProperties'
    AnnotationFile:
      title: File
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationFileProperties'
    AnnotationWorkspaceContainer:
      title: Workspace Container
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationWorkspaceContainerProperties'
    AnnotationRankedChoices:
      title: Ranked Choices
      description: >-
        A list of choices where the beginning of the list is preferred. Ties are
        not allowed.
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationRankedChoicesProperties'
    AnnotationRankedGroups:
      title: Ranked Groups
      description: >-
        A list of choices where the beginning of the list is preferred. When
        there's a tie, multiple choices will be at the same index.
      allOf:
        - $ref: '#/components/schemas/BaseAnnotation'
        - $ref: '#/components/schemas/AnnotationRankedGroupsProperties'
    BaseAnnotation:
      type: object
      required:
        - id
        - key
        - type
      properties:
        id:
          $ref: '#/components/schemas/AnnotationId'
          description: Unique identifier for the annotation.
          example: an_abc123efg456
        key:
          $ref: '#/components/schemas/AnnotationKey'
          description: Key for the annotation.
          example: formatting
        type:
          type: string
          description: The type of the value and the possible_values, if they exist.
        title:
          $ref: '#/components/schemas/Title'
          example: Response Formatting
        description:
          $ref: '#/components/schemas/Description'
          example: Does the response contain issues with formatting?
        labels:
          type: array
          description: String representation of the possible options.
          items:
            $ref: '#/components/schemas/AnnotationLabel'
          example:
            - Major Issues
            - Minor Issues
            - No Issues
        metadata:
          $ref: '#/components/schemas/AnnotationMetadata'
    AnnotationIntegerProperties:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/IntegerValue'
        possible_values:
          type: array
          description: The possible values for this annotation.
          items:
            $ref: '#/components/schemas/IntegerValue'
            example:
              - 1
              - 2
              - 3
    AnnotationBooleanProperties:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/BooleanValue'
        possible_values:
          type: array
          description: The possible values for this annotation.
          items:
            $ref: '#/components/schemas/BooleanValue'
            example:
              - true
              - false
    AnnotationTextProperties:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/TextValue'
    AnnotationCategoryProperties:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/CategoryValue'
        possible_values:
          type: array
          description: The possible values for this annotation.
          items:
            $ref: '#/components/schemas/CategoryValue'
            example:
              - Brainstorming
              - Critical Thinking
              - Math
    AnnotationCategoryMultipleProperties:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/CategoryMultipleValue'
        possible_values:
          $ref: '#/components/schemas/CategoryMultipleValue'
          description: The possible values for this annotation.
          example:
            - Brainstorming
            - Critical Thinking
            - Math
    AnnotationFileProperties:
      type: object
      properties:
        value:
          oneOf:
            - $ref: '#/components/schemas/DetailedFile'
              title: File
            - $ref: '#/components/schemas/MultipleFiles'
              title: Multiple Attachments
    AnnotationWorkspaceContainerProperties:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/WorkspaceContainerValue'
          title: Workspace Container
    AnnotationRankedChoicesProperties:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/RankedChoice'
          example:
            - model_1
            - model_3
            - model_2
    AnnotationRankedGroupsProperties:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/RankedGroup'
          example:
            - - model_a
              - model_c
            - - model_b
    AnnotationKey:
      type: string
      description: Key for the annotation.
      example: formatting
    Title:
      type: string
      description: Title of the annotation.
      example: Overall Response Score
    Description:
      type: string
      description: Further details about the question.
      example: How would you rate the entire response overall?
    AnnotationLabel:
      type: string
      description: A string representation of the annotation.
    AnnotationMetadata:
      type: object
      properties:
        criteria:
          $ref: '#/components/schemas/ExpandableAnnotation'
    IntegerValue:
      description: Integer type annotation value.
      type: integer
      example: 3
    BooleanValue:
      description: Boolean type annotation value.
      type: boolean
      example: true
    TextValue:
      type: string
      description: String type annotation value.
      example: 'There were multiple issues in the response: 1. ...'
    CategoryValue:
      type: string
      description: Single-select category annotation.
      example: Critical Thinking
    CategoryMultipleValue:
      description: Multi-select category annotation.
      example:
        - Critical Thinking
        - Math
      type: array
      items:
        type: string
    DetailedFile:
      oneOf:
        - $ref: '#/components/schemas/BasicFile'
          title: File
        - $ref: '#/components/schemas/ImageFile'
          title: Detailed Image File
        - $ref: '#/components/schemas/AudioFile'
          title: Detailed Audio File
    MultipleFiles:
      type: array
      items:
        $ref: '#/components/schemas/BasicFile'
    WorkspaceContainerValue:
      type: object
      properties:
        workspace_id:
          type: string
          description: ID of the workspace.
        workspace_config:
          $ref: '#/components/schemas/WorkspaceContainerConfig'
        last_code_run_event:
          $ref: '#/components/schemas/WorkspaceExecutionData'
          type: object
        output_files:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceFile'
        stdout_output:
          $ref: '#/components/schemas/ContentAndUrl'
          description: Standard output stream of the workspace.
        stderr_output:
          $ref: '#/components/schemas/ContentAndUrl'
          description: Standard error stream of the workspace.
        test_stdout_output:
          $ref: '#/components/schemas/ContentAndUrl'
          description: Standard output stream of the workspace for test cases.
        test_stderr_output:
          $ref: '#/components/schemas/ContentAndUrl'
          description: Standard error stream of the workspace for test cases.
    RankedChoice:
      type: string
    RankedGroup:
      type: array
      items:
        type: string
    ExpandableAnnotation:
      oneOf:
        - $ref: '#/components/schemas/AnnotationId'
        - type: object
          description: >-
            A full Annotation object. This is defined as a generic object to
            avoid circular references that some tools cannot handle.
    BasicFile:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/Bytes'
          description: The base64-encoded content of the file.
        mime_type:
          $ref: '#/components/schemas/MimeType'
          description: The MIME type of the file, indicating its format.
        scale_url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the location of the file in Scale's storage.
        url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the source location of the file.
        name:
          $ref: '#/components/schemas/FileName'
          description: The name of the file.
    ImageFile:
      type: object
      properties:
        mime_type:
          $ref: '#/components/schemas/MimeType'
          description: The MIME type of the file, indicating its format.
        scale_url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the location of the file in Scale's storage.
        url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the source location of the file.
        name:
          type: string
          description: The name of the image file.
        file_size_in_bytes:
          type: integer
          description: The size of the file in bytes.
    AudioFile:
      type: object
      properties:
        mime_type:
          $ref: '#/components/schemas/MimeType'
          description: The MIME type of the file, indicating its format.
        scale_url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the scale location of the file.
        url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the source location of the file.
        duration:
          type: number
          description: The duration of the audio file in seconds.
        transcript:
          type: string
          description: The transcript of the audio file.
        transcript_url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the location of the transcript.
        transcript_start:
          type: number
          description: The start time of the transcript in seconds.
        transcript_end:
          type: number
          description: The end time of the transcript in seconds.
    WorkspaceContainerConfig:
      type: object
      required:
        - workspace_id
        - workspace_url
        - workspace_token
        - expires_at
        - inactivity_freeze_time
      properties:
        workspace_id:
          type: string
          description: ID of the workspace.
        workspace_url:
          $ref: '#/components/schemas/URL'
          type: string
          description: URL of the workspace.
        workspace_token:
          type: string
          description: Token of the workspace.
        expires_at:
          type: string
          description: Expiration time of the workspace.
        inactivity_freeze_time:
          type: integer
          description: Inactivity freeze time of the workspace.
        force_enable_workspace_access:
          type: boolean
          description: Force enable workspace access.
        workspace_image_version:
          type: integer
          description: Image version of the workspace.
    WorkspaceExecutionData:
      type: object
      properties:
        id:
          type: string
          description: ID of the workspace.
        result:
          type: object
          properties:
            status:
              type: object
              properties:
                code:
                  type: number
                  description: Status code of the workspace execution.
                name:
                  type: string
                  description: Execution full status.
            time:
              type: number
              description: Time taken for last execution.
            score:
              type: number
              description: Score of the output of last execution.
    WorkspaceFile:
      type: object
      required:
        - scale_url
      properties:
        file_name:
          type: string
          description: File name
        scale_url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the scale location of the file.
        url:
          $ref: '#/components/schemas/URL'
          description: A URL pointing to the source location of the file.
        file_language:
          type: string
          description: Coding language of the file.
        file_content:
          type: string
          description: Content of the file.
    ContentAndUrl:
      type: object
      properties:
        content:
          type: string
          description: The content of the file.
        url:
          $ref: '#/components/schemas/URL'
          type: string
          description: A URL pointing to the source location of the file.
        scale_url:
          $ref: '#/components/schemas/URL'
          type: string
          description: A URL pointing to the scale location of the file.
    Bytes:
      type: string
      format: byte
      description: Base-64 encoded data
    MimeType:
      type: string
      example: text/plain
      description: The MIME type of the content, such as application/json or image/png.
    URL:
      type: string
      description: A URL string pointing to a resource.
    FileName:
      type: string
      description: The name of the file.
  securitySchemes:
    bearerAuth:
      description: >-
        Your API Key is the Bearer token. See the
        [Authentication](/get-started/authentication) section to learn how to
        access your key.
      type: http
      scheme: bearer
    basicAuth:
      description: >-
        Basic HTTP Authentication. Your API Key is your username.  Learn more
        about setting up Authentication [here](/get-started/authentication).
      type: http
      scheme: basic

````