> ## Documentation Index > Fetch the complete documentation index at: https://platform-docs.sarj.ai/llms.txt > Use this file to discover all available pages before exploring further. # Fetch Sarj.ai voice call details by call_id > Fetch details of a Sarj.ai voice call by call_id: status, phone_number, scenario_id, language, direction (inbound/outbound), scenario variables, duration (seconds), recording_url (signed download link), transcript (list of spoken messages), and timestamps (created_at, updated_at, started_at, ended_at). Use this whenever the user asks about a specific call, phone conversation, or voice interaction by its call_id — do not query other tools. ## OpenAPI ````yaml /api-reference/openapi.json get /calls/{call_id} openapi: 3.1.0 info: title: Sarj.ai Developer API description: > Public API for programmatic access to the **Sarj.ai voice platform**. > [!TIP] > **New here?** Start with the [Getting Started guide](https://platform-docs.sarj.ai/getting-started) > to go from API key to first call in under 5 minutes. > > **Building with AI agents?** See the [MCP Server guide](https://platform-docs.sarj.ai/mcp-server) > to connect Claude Code, Cursor, or any MCP-compatible agent. --- ## Authentication All authenticated endpoints require a **Bearer token** in the `Authorization` header: ``` Authorization: Bearer ``` Generate an API key from [platform.sarj.ai/api-keys](https://platform.sarj.ai/api-keys). > [!WARNING] > If you receive a `401 Unauthorized` response, your key may be invalid, > expired, or missing. Check the `error.type` field in the response body. --- ## Response Format **Success** ```json { "data": { ... }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` **Error** ```json { "error": { "type": "unauthorized", "message": "Authentication required." }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` Always branch on `error.type` — the `message` field is for humans only. --- ## Support Include `meta.request_id` in all support tickets for faster resolution. license: name: Apache 2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://platform-api.sarj.ai/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: System description: Service health and status. - name: Calls description: Create outbound voice calls and retrieve call details and transcripts. externalDocs: description: Sarj.ai Documentation url: https://platform-docs.sarj.ai paths: /calls/{call_id}: get: tags: - Calls summary: Fetch Sarj.ai voice call details by call_id description: >- Fetch details of a Sarj.ai voice call by call_id: status, phone_number, scenario_id, language, direction (inbound/outbound), scenario variables, duration (seconds), recording_url (signed download link), transcript (list of spoken messages), and timestamps (created_at, updated_at, started_at, ended_at). Use this whenever the user asks about a specific call, phone conversation, or voice interaction by its call_id — do not query other tools. operationId: getCall parameters: - name: call_id in: path required: true schema: type: string title: Call Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ApiResponse_PublicCallDetail_' example: data: id: call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b status: completed phone_number: '+966512345678' scenario_id: 550e8400-e29b-41d4-a716-446655440000 language: ar direction: outbound variables: customer_name: Ahmad order_id: ORD-123 duration: 142 recording_url: >- https://storage.googleapis.com/sarj-recordings/calls/8f9b2c1e.mp4?X-Goog-Signature=... transcript: - role: assistant content: Hello Ahmad, calling about order ORD-123. - role: user content: Yes, hi. - role: assistant content: Your order is ready for delivery tomorrow. created_at: '2026-04-12T10:30:00Z' updated_at: '2026-04-12T10:32:22Z' started_at: '2026-04-12T10:30:05Z' ended_at: '2026-04-12T10:32:22Z' meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: unauthorized message: Authentication required. meta: {} '403': description: API key not associated with an organization. content: application/json: example: error: type: no_organization message: API key is not associated with an organization. meta: request_id: 550e8400-e29b-41d4-a716-446655440000 schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Call not found. content: application/json: example: error: type: call_not_found message: >- Call call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b was not found. call_id: call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b meta: request_id: 550e8400-e29b-41d4-a716-446655440000 schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - label: Python (SDK) lang: Python source: >- import os from sarj_platform_sdk import SDK sdk = SDK(api_key_auth=os.environ["SARJ_API_KEY"]) res = sdk.calls.get_call(call_id="call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b") call = res.data print(f"Status: {call.status}, duration: {call.duration}") - label: curl lang: bash source: >- curl https://platform-api.sarj.ai/api/v1/calls/call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b \ -H "Authorization: Bearer $SARJ_API_KEY" - label: Python (requests) lang: Python source: |- import os import requests call_id = "call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b" response = requests.get( f"https://platform-api.sarj.ai/api/v1/calls/{call_id}", headers={ "Authorization": f"Bearer {os.environ['SARJ_API_KEY']}", }, ) response.raise_for_status() call = response.json()["data"] print(f"Status: {call['status']}, duration: {call['duration']}") - label: TypeScript lang: TypeScript source: |- const callId = "call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b"; const response = await fetch( `https://platform-api.sarj.ai/api/v1/calls/${callId}`, { headers: { "Authorization": `Bearer ${process.env.SARJ_API_KEY}`, }, }, ); if (!response.ok) throw new Error(`HTTP ${response.status}`); const { data: call } = await response.json(); console.log(`Status: ${call.status}, duration: ${call.duration}`); components: schemas: ApiResponse_PublicCallDetail_: properties: data: $ref: '#/components/schemas/PublicCallDetail' meta: $ref: '#/components/schemas/ResponseMeta' additionalProperties: false type: object required: - data title: ApiResponse[PublicCallDetail] ErrorResponse: properties: error: oneOf: - $ref: '#/components/schemas/ValidationErrorPayload' - $ref: '#/components/schemas/UnauthorizedPayload' - $ref: '#/components/schemas/NotFoundPayload' - $ref: '#/components/schemas/InternalErrorPayload' - $ref: '#/components/schemas/PhoneNumberBlockedPayload' - $ref: '#/components/schemas/CallLimitExceededPayload' - $ref: '#/components/schemas/OutboundCallFailedPayload' - $ref: '#/components/schemas/ScenarioNotFoundPayload' - $ref: '#/components/schemas/ScenarioForbiddenPayload' - $ref: '#/components/schemas/NoOrganizationPayload' - $ref: '#/components/schemas/CallNotFoundPayload' - $ref: '#/components/schemas/OauthInvalidRedirectUriPayload' title: Error discriminator: propertyName: type mapping: call_limit_exceeded: $ref: '#/components/schemas/CallLimitExceededPayload' call_not_found: $ref: '#/components/schemas/CallNotFoundPayload' internal_error: $ref: '#/components/schemas/InternalErrorPayload' no_organization: $ref: '#/components/schemas/NoOrganizationPayload' not_found: $ref: '#/components/schemas/NotFoundPayload' oauth_invalid_redirect_uri: $ref: '#/components/schemas/OauthInvalidRedirectUriPayload' outbound_call_failed: $ref: '#/components/schemas/OutboundCallFailedPayload' phone_number_blocked: $ref: '#/components/schemas/PhoneNumberBlockedPayload' scenario_forbidden: $ref: '#/components/schemas/ScenarioForbiddenPayload' scenario_not_found: $ref: '#/components/schemas/ScenarioNotFoundPayload' unauthorized: $ref: '#/components/schemas/UnauthorizedPayload' validation_error: $ref: '#/components/schemas/ValidationErrorPayload' meta: $ref: '#/components/schemas/ResponseMeta' additionalProperties: false type: object required: - error title: ErrorResponse description: |- Standard envelope for all public API error responses. `error` is a discriminated union — branch on `error.type` to access variant-specific fields. Clients MUST treat unknown `type` values as retryable internal errors to preserve forward compatibility. PublicCallDetail: properties: id: type: string title: Id description: Unique call identifier. examples: - call_550e8400-e29b-41d4-a716-446655440000 status: anyOf: - $ref: '#/components/schemas/CallStatus' - type: 'null' description: Current call status. examples: - in_progress phone_number: anyOf: - type: string - type: 'null' title: Phone Number description: Destination phone number. scenario_id: anyOf: - type: string - type: 'null' title: Scenario Id description: Scenario used for this call. language: anyOf: - $ref: '#/components/schemas/Language' - type: 'null' description: Language the call was conducted in. direction: anyOf: - $ref: '#/components/schemas/PhoneDirection' - type: 'null' description: Call direction (inbound or outbound). variables: additionalProperties: true type: object title: Variables description: >- Template variables that were injected into the scenario. Defaults to an empty object for non-custom scenarios. duration: anyOf: - type: integer - type: 'null' title: Duration description: Total call duration in seconds. Null until the call ends. recording_url: anyOf: - type: string - type: 'null' title: Recording Url description: >- Signed, time-limited URL to download the call recording. Null when the call has not ended or no recording exists. transcript: anyOf: - items: $ref: '#/components/schemas/PublicTranscriptMessage' type: array - type: 'null' title: Transcript description: >- Conversation transcript as an ordered list of spoken messages. Null until the call ends. created_at: type: string format: date-time title: Created At description: Timestamp when the call was created. updated_at: type: string format: date-time title: Updated At description: Timestamp of the most recent update to the call. started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: Timestamp when the call was answered. ended_at: anyOf: - type: string format: date-time - type: 'null' title: Ended At description: Timestamp when the call ended. additionalProperties: false type: object required: - id - created_at - updated_at title: PublicCallDetail ResponseMeta: properties: request_id: anyOf: - type: string - type: 'null' title: Request Id description: >- Unique identifier for this request, mirrored in the `X-Request-ID` response header. Supply your own via the `X-Request-ID` request header (max 128 chars, ASCII printable); otherwise the server generates a UUID v4. Include in support tickets. examples: - 550e8400-e29b-41d4-a716-446655440000 additionalProperties: false type: object title: ResponseMeta description: Contains request-level metadata included with every public API response. ValidationErrorPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: validation_error title: Type default: validation_error field_violations: items: $ref: '#/components/schemas/FieldViolation' type: array title: Field Violations description: Per-field validation details. additionalProperties: false type: object required: - message - field_violations title: ValidationErrorPayload UnauthorizedPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: unauthorized title: Type default: unauthorized additionalProperties: false type: object required: - message title: UnauthorizedPayload NotFoundPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: not_found title: Type default: not_found additionalProperties: false type: object required: - message title: NotFoundPayload InternalErrorPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: internal_error title: Type default: internal_error additionalProperties: false type: object required: - message title: InternalErrorPayload PhoneNumberBlockedPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: phone_number_blocked title: Type default: phone_number_blocked phone_number: type: string title: Phone Number description: The phone number that is blocked. additionalProperties: false type: object required: - message - phone_number title: PhoneNumberBlockedPayload CallLimitExceededPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: call_limit_exceeded title: Type default: call_limit_exceeded phone_number: type: string title: Phone Number description: The phone number that hit the limit. call_limit: type: integer title: Call Limit description: The per-number call limit that was reached. additionalProperties: false type: object required: - message - phone_number - call_limit title: CallLimitExceededPayload OutboundCallFailedPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: outbound_call_failed title: Type default: outbound_call_failed reason: type: string title: Reason description: Stable-ish reason string from the call service. additionalProperties: false type: object required: - message - reason title: OutboundCallFailedPayload ScenarioNotFoundPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: scenario_not_found title: Type default: scenario_not_found scenario_id: type: string title: Scenario Id additionalProperties: false type: object required: - message - scenario_id title: ScenarioNotFoundPayload ScenarioForbiddenPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: scenario_forbidden title: Type default: scenario_forbidden scenario_id: type: string title: Scenario Id additionalProperties: false type: object required: - message - scenario_id title: ScenarioForbiddenPayload NoOrganizationPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: no_organization title: Type default: no_organization additionalProperties: false type: object required: - message title: NoOrganizationPayload CallNotFoundPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: call_not_found title: Type default: call_not_found call_id: type: string title: Call Id additionalProperties: false type: object required: - message - call_id title: CallNotFoundPayload OauthInvalidRedirectUriPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: oauth_invalid_redirect_uri title: Type default: oauth_invalid_redirect_uri redirect_uri: type: string title: Redirect Uri additionalProperties: false type: object required: - message - redirect_uri title: OauthInvalidRedirectUriPayload CallStatus: type: string enum: - queued - in_progress - completed - timeout - user_rejected - max_duration_reached - failed - ringing - voicemail - dialing - cancelled - expired title: CallStatus Language: type: string enum: - en - ar - ur title: Language description: Language codes in ISO 639-1 PhoneDirection: type: string enum: - inbound - outbound title: PhoneDirection PublicTranscriptMessage: properties: role: type: string enum: - user - assistant title: Role description: >- Speaker role: 'user' for the called party, 'assistant' for the AI agent. content: type: string title: Content description: Text of the spoken message. additionalProperties: false type: object required: - role - content title: PublicTranscriptMessage FieldViolation: properties: field: type: string title: Field description: >- Dot-separated path to the invalid field (e.g. `phone_number.country_code`). examples: - phone_number.country_code message: type: string title: Message description: Human-readable description of the violation. examples: - Must start with + additionalProperties: false type: object required: - field - message title: FieldViolation securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- API key from your Sarj.ai dashboard. Pass as: Authorization: Bearer ````