> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Agent Phone Number History > Get the history of phone numbers linked to and detached from a DialNexa agent. Read only Get agent phone number history to audit which numbers an agent has used and when. Each row is one link: a number attached to the agent in one direction, from `linked_at` until `unlinked_at`. Rows are ordered newest first. ## When to use this * **Call investigations**: find which agent a number routed to at the time of a call. * **Change audits**: see who attached or detached a number and why a link ended. ## Before you begin Get the agent ID from [List Agents](/docs/api-reference/v1/agents/list). ## Get agent phone number history request ```bash theme={null} curl "https://api.dialnexa.com/v1/agents/agent_2g7Xy3tY53gRlp/phone-numbers/history" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Read the history rows | Field | Meaning | | - | - | | `phone_number_id`, `phone_number`, `country_iso` | The number that was linked. | | `direction` | `inbound` or `outbound`. | | `linked_at`, `linked_by` | When the link started and who created it, when known. | | `unlinked_at`, `unlinked_by` | When the link ended and who ended it. `unlinked_at` is null for a current link. | | `unlink_reason` | `manual` (detached), `agent_deleted`, `number_deleted`, or `number_released` (the rental expired or the number was withdrawn). Null for a current link. | ## Verify the result A `200` response contains `data` as an array. An empty array means no link is recorded for the agent. ## Errors and recovery * `401 Unauthorized` means the API key is missing or invalid. * `404 Not Found` means the agent does not exist in this workspace or was deleted. Reads are safe to retry. ## Related endpoints * [List Agent Phone Numbers](/docs/api-reference/v1/agents/list-phone-numbers) * [Attach Agent Phone Number](/docs/api-reference/v1/agents/attach-phone-number) * [Detach Agent Phone Number](/docs/api-reference/v1/agents/detach-phone-number) ## OpenAPI ````yaml GET /v1/agents/{agentId}/phone-numbers/history openapi: 3.0.0 info: title: DialNexa API description: Public `/v1` REST API for the DialNexa voice AI platform. version: 1.0.0 servers: - url: https://api.dialnexa.com description: DialNexa production API security: - bearer: [] tags: - name: Agents - name: Batch Calls - name: Calls - name: Knowledge Base - name: Languages - name: LLMs - name: Phone Numbers - name: Transcribers - name: Webhooks - name: Voices - name: Workflows - name: Workflow Leads - name: Authentication - name: Agent Builder paths: /v1/agents/{agentId}/phone-numbers/history: get: tags: - Agents summary: Get Agent Phone Number History description: >- Returns every link between the agent and a phone number, newest first, with when each link started and ended and why it ended. operationId: getAgentPhoneNumberHistory parameters: - name: agentId in: path required: true schema: example: agent_2g7Xy3tY53gRlp type: string description: Agent ID from List Agents. responses: '200': description: Successful response. content: application/json: schema: type: object properties: success: type: boolean error: type: boolean statusCode: type: integer message: type: string data: type: array items: type: object properties: id: type: string description: Link record ID. agent_id: example: agent_2g7Xy3tY53gRlp type: string phone_number_id: type: string example: phn_abc123 direction: type: string enum: - inbound - outbound description: >- inbound: the number rings this agent. outbound: the agent calls from it. linked_at: type: string format: date-time linked_by: type: string nullable: true description: User who created the link, when known. unlinked_at: type: string format: date-time nullable: true description: Null while the link is current. unlinked_by: type: string nullable: true description: User who ended the link, when known. unlink_reason: type: string nullable: true enum: - manual - agent_deleted - number_deleted - number_released description: >- Why the link ended: manual (detached), agent_deleted, number_deleted, or number_released (the rental expired or the number was withdrawn). Null while the link is current. phone_number: type: string nullable: true example: '9876543210' description: The number without its country calling code. country_iso: type: string nullable: true example: '91' required: - id - agent_id - phone_number_id - direction - linked_at - unlinked_at - unlink_reason timestamp: type: string format: date-time required: - success - error - statusCode - message - data - timestamp examples: success: value: success: true error: false statusCode: 200 message: Success data: - id: k2m9q4wz1abcde direction: inbound linked_at: '2026-09-30T06:00:00.000Z' linked_by: null unlinked_at: '2026-09-30T08:00:00.000Z' unlinked_by: null unlink_reason: manual agent_id: agent_2g7Xy3tY53gRlp phone_number_id: phn_abc123 phone_number: '9876543210' country_iso: '91' timestamp: '2026-09-07T06:00:00.000Z' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: statusCode: 401 error: true success: false data: [] message: Invalid API key errors: [] '404': description: The agent is not in this workspace. content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' examples: agentNotFound: value: statusCode: 404 error: true success: false data: [] message: Agent agent_2g7Xy3tY53gRlp not found in your organization. errors: [] security: - bearer: [] components: schemas: ErrorResponse: type: object description: Error body on endpoints without response filtering. properties: statusCode: type: integer example: 404 error: type: boolean enum: - true success: type: boolean enum: - false data: oneOf: - type: object properties: code: type: string description: Machine-readable refusal code. - type: array items: {} description: >- For a coded refusal, an object with code and the details listed for that code. Otherwise an empty array. message: type: string errors: type: array items: type: string description: Validation messages for a 400. Empty for other errors. required: - statusCode - error - success - data - message - errors CodedErrorResponse: type: object description: Error body for a coded refusal; data carries code and its details. properties: statusCode: type: integer example: 404 error: type: boolean enum: - true success: type: boolean enum: - false data: oneOf: - type: object properties: code: type: string description: Machine-readable refusal code. - type: array items: {} description: >- For a coded refusal, an object with code and the details listed for that code. Otherwise an empty array. message: type: string errors: type: array items: type: string description: Validation messages for a 400. Empty for other errors. required: - statusCode - error - success - data - message - errors securitySchemes: bearer: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.