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

# Get a persona

> Returns a specific persona by its ID.



## OpenAPI

````yaml /api-reference/openapi.documented.json get /v1/persona/{personaId}
openapi: 3.1.0
info:
  title: Roark Analytics API
  description: >-
    The Roark Analytics API gives you access to the same API that powers the
    award winning Roark Analytics platform.
  version: 1.0.0
servers:
  - description: Production
    url: https://api.roark.ai
security:
  - Bearer: []
tags:
  - name: Health
    x-displayName: Health
  - name: Authentication
    x-displayName: Current credential
  - name: Project API Key
    x-displayName: Project API keys
  - name: Personal API Key
    x-displayName: Personal API keys
  - name: Agent
    x-displayName: Agents
  - name: Agent Endpoint
    x-displayName: Endpoints
  - name: Tool
    x-displayName: Tools
  - name: Agent Setup
    x-displayName: Automatic test setup
  - name: Autoimprove
    x-displayName: Autoimprove
  - name: Customer Flow
    x-displayName: Customer flows
  - name: Customer Flow Folder
    x-displayName: Customer flow folders
  - name: Simulation Persona
    x-displayName: Personas
  - name: Simulation Environment
    x-displayName: Environments
  - name: Simulation Template
    x-displayName: Templates
  - name: Simulation Run Plan
    x-displayName: Plans
  - name: Simulation Run
    x-displayName: Runs
  - name: Simulation Tool Mock
    x-displayName: Tool mocks and fixtures
  - name: Metric
    x-displayName: Definitions
  - name: Metric Variant
    x-displayName: Variants
  - name: Metric Policy
    x-displayName: Policies
  - name: Metric Collection Job
    x-displayName: Collection jobs
  - name: Call
    x-displayName: Calls
  - name: Chat
    x-displayName: Chats
  - name: Customer
    x-displayName: Customers
  - name: Issue
    x-displayName: Issues
  - name: Analytics
    x-displayName: Analytics
  - name: Dashboard
    x-displayName: Dashboards
  - name: Live Report
    x-displayName: Reports
  - name: Agent Connection
    x-displayName: Agent platforms
  - name: Calendar Connection
    x-displayName: Calendars
  - name: MCP Server Connection
    x-displayName: MCP servers
  - name: Knowledge Base
    x-displayName: Knowledge bases
  - name: HTTP Request Definition
    x-displayName: HTTP request definitions
  - name: Webhook
    x-displayName: Webhooks
  - name: Config
    x-displayName: Config as code
  - name: Organization Project
    x-displayName: Projects
  - name: Organization Project Member
    x-displayName: Project members
  - name: Usage
    x-displayName: Usage
  - name: Benchmark
    x-displayName: Benchmarks
paths:
  /v1/persona/{personaId}:
    get:
      tags:
        - Simulation Persona
      summary: Get a persona
      description: Returns a specific persona by its ID.
      operationId: getV1PersonaByPersonaId
      parameters:
        - name: personaId
          in: path
          required: true
          description: The ID of the persona to retrieve
          schema:
            type: string
      responses:
        '200':
          description: The requested persona
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier of the persona
                      name:
                        type: string
                        description: >-
                          The name the agent will identify as during
                          conversations
                      displayName:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Label shown in place of the name across the dashboard
                          (e.g. a short descriptor like "Irate Escalator"). The
                          persona still identifies as `name` on calls. Omit or
                          set null to display the name itself.
                      description:
                        type:
                          - string
                          - 'null'
                        description: Human-readable description of the persona
                      language:
                        type: string
                        enum:
                          - EN
                          - ES
                          - DE
                          - HI
                          - FR
                          - NL
                          - AR
                          - EL
                          - IT
                          - ID
                          - TH
                          - JA
                          - TL
                          - MS
                          - ZH
                          - TR
                          - PT
                          - HE
                        description: Primary language ISO 639-1 code for the persona
                      secondaryLanguage:
                        type:
                          - string
                          - 'null'
                        enum:
                          - EN
                        description: >-
                          Secondary language ISO 639-1 code for code-switching
                          (e.g., Hinglish, Spanglish)
                      understoodLanguages:
                        type: array
                        items:
                          type: string
                          enum:
                            - EN
                            - ES
                            - DE
                            - HI
                            - FR
                            - NL
                            - AR
                            - EL
                            - IT
                            - ID
                            - TH
                            - JA
                            - TL
                            - MS
                            - ZH
                            - TR
                            - PT
                            - HE
                        minItems: 1
                        description: >-
                          Languages the persona can understand. Multilingual
                          combinations are limited by multilingual speech
                          recognition support.
                      accent:
                        type: string
                        enum:
                          - US
                          - US_X_SOUTH
                          - GB
                          - ES
                          - DE
                          - IN
                          - FR
                          - NL
                          - SA
                          - GR
                          - AU
                          - IT
                          - ID
                          - TH
                          - JP
                          - NZ
                          - PH
                          - SG
                          - MY
                          - HK
                          - TR
                          - PT
                          - IL
                        description: >-
                          Accent of the persona, defined using ISO 3166-1
                          alpha-2 country codes with optional variants
                      age:
                        type: string
                        enum:
                          - CHILD
                          - TEENAGER
                          - ADULT
                          - ELDERLY
                        default: ADULT
                        description: >-
                          How old the caller sounds and behaves. Only ages the
                          persona's accent has a voice for are accepted;
                          defaults to ADULT, which every accent supports.
                      gender:
                        type: string
                        enum:
                          - MALE
                          - FEMALE
                        description: Gender of the persona
                      backgroundNoise:
                        type: string
                        enum:
                          - NONE
                          - AIRPORT
                          - CHILDREN_PLAYING
                          - CITY
                          - COFFEE_SHOP
                          - CONSTRUCTION
                          - CRYING_BABY
                          - DRIVING
                          - LIBRARY
                          - OFFICE
                          - THUNDERSTORM
                          - TRAIN
                        default: NONE
                        description: Background noise setting
                      speechPace:
                        type: string
                        enum:
                          - SUPER_SLOW
                          - SLOW
                          - NORMAL
                          - FAST
                          - SUPER_FAST
                        default: NORMAL
                        description: Speech pace of the persona
                      speechClarity:
                        type: string
                        enum:
                          - CLEAR
                          - VAGUE
                          - RAMBLING
                        default: CLEAR
                        description: Speech clarity of the persona
                      hasDisfluencies:
                        type: boolean
                        default: false
                        description: >-
                          Whether the persona uses filler words like "um" and
                          "uh"
                      baseEmotion:
                        type: string
                        enum:
                          - NEUTRAL
                          - CHEERFUL
                          - CONFUSED
                          - FRUSTRATED
                          - SKEPTICAL
                          - RUSHED
                          - DISTRACTED
                          - ANGRY
                          - ANXIOUS
                          - SAD
                        default: NEUTRAL
                        description: Base emotional state of the persona
                      intentClarity:
                        type: string
                        enum:
                          - CLEAR
                          - INDIRECT
                          - VAGUE
                        default: CLEAR
                        description: How clearly the persona expresses their intentions
                      confirmationStyle:
                        type: string
                        enum:
                          - EXPLICIT
                          - VAGUE
                        default: EXPLICIT
                        description: How the persona confirms information
                      memoryReliability:
                        type: string
                        enum:
                          - HIGH
                          - LOW
                        default: HIGH
                        description: How reliable the persona's memory is
                      responseTiming:
                        type: string
                        enum:
                          - RELAXED
                          - NORMAL
                          - QUICK
                          - BARGE_IN
                        default: NORMAL
                        description: >-
                          Deprecated and inert: it no longer affects the call.
                          It set how long the persona waited once the agent
                          stopped talking, and measured across production
                          simulations it moved the reply gap by less than the
                          noise floor, because model and speech latency dominate
                          it. Every persona now uses one voice-activity profile.
                          Use `interruption` for a caller who talks over the
                          agent. Still accepted and stored so existing clients
                          keep working. BARGE_IN is stored as `responseTiming:
                          QUICK` with `interruption: OCCASIONAL`.
                      interruption:
                        type: string
                        enum:
                          - 'OFF'
                          - BACKCHANNEL
                          - OCCASIONAL
                          - HEAVY
                        default: 'OFF'
                        description: >-
                          How much the persona talks over the agent while it is
                          still speaking. OFF waits its turn. BACKCHANNEL makes
                          listening noises ("mm-hm") over the agent without
                          taking the floor, which tests whether the agent
                          wrongly stops for them. OCCASIONAL also cuts in where
                          a caller like this plausibly would, and HEAVY does so
                          readily, though never on every turn. The moments are
                          chosen from what the agent is saying, such as reading
                          back a number or starting a long explanation, not on a
                          timer. A customer flow can also say exactly when to
                          cut in, which applies at any level.
                      backstoryPrompt:
                        type:
                          - string
                          - 'null'
                        description: >-
                          Background story and behavioral patterns for the
                          persona
                        example: A busy professional calling during lunch break
                      idleMessages:
                        type:
                          - array
                          - 'null'
                        items:
                          type: string
                        description: >-
                          Messages the persona will say when the agent goes
                          silent during a call. null = "Automatic":
                          language-appropriate defaults are used at call time.
                      idleTimeoutSeconds:
                        type: integer
                        minimum: 5
                        maximum: 60
                        default: 10
                        description: >-
                          Seconds of silence before the persona sends an idle
                          message
                      idleMessageMaxSpokenCount:
                        type: integer
                        minimum: 1
                        maximum: 10
                        default: 3
                        description: >-
                          Maximum number of idle messages the persona will send
                          before giving up
                      idleMessageResetCountOnUserSpeechEnabled:
                        type: boolean
                        default: true
                        description: >-
                          Whether the idle message counter resets when the agent
                          speaks
                      properties:
                        type: object
                        additionalProperties: {}
                        default: {}
                        description: Additional custom properties about the persona
                        example:
                          age: 35
                          zipCode: '94105'
                          occupation: Software Engineer
                      phoneNumber:
                        type: string
                        description: >-
                          The E.164 number every call with this persona uses,
                          when Roark has pinned one for your project. Present
                          only when set; read-only.
                        example: '+19312830919'
                      createdAt:
                        type: string
                        description: Creation timestamp
                      updatedAt:
                        type: string
                        description: Last update timestamp
                    required:
                      - id
                      - name
                      - language
                      - understoodLanguages
                      - accent
                      - age
                      - gender
                      - backgroundNoise
                      - speechPace
                      - speechClarity
                      - hasDisfluencies
                      - baseEmotion
                      - intentClarity
                      - confirmationStyle
                      - memoryReliability
                      - responseTiming
                      - interruption
                      - idleMessages
                      - idleTimeoutSeconds
                      - idleMessageMaxSpokenCount
                      - idleMessageResetCountOnUserSpeechEnabled
                      - properties
                      - createdAt
                      - updatedAt
                required:
                  - data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Roark from '@roarkanalytics/sdk';


            const client = new Roark({
              bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
            });


            const response = await
            client.simulationPersona.getByID('personaId');


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from roark_analytics import Roark

            client = Roark(
                bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
            )
            response = client.simulation_persona.get_by_id(
                "personaId",
            )
            print(response.data)
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - validation
            - authentication
            - forbidden
            - not_found
            - conflict
            - payment_required
            - rate_limit
            - internal
          description: The error type category
          examples:
            - validation
            - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
            - invalid_parameter
            - missing_required_field
            - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
            - The request was invalid
            - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
            - email
            - user_id
        details:
          description: Additional error context information
      required:
        - type
        - code
        - message
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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