# Get DID Histories

Returns a list of DID history records for your account. Only records from the last `90` days are available.

## Request

HTTP Method: `GET`

URI Path: `/v3/did_history`

Note

For all returned data attributes, see [Did History Object](did-history-object.html).

### URI Query Parameters

| Name | Type | Is Required? | Description |
| --- | --- | --- | --- |
| filter[<filter\_name>] | `string` | No | [Filtering](../../../specification/filtering.html#api-filters) |
| fields[did\_history] | `string` | No | [Sparse fieldsets](../../../specification/sparse-fieldsets.html#api-sparse-fieldsets) |
| sort | `string` | No | [Sorting](../../../specification/sorting.html#api-sorting) |
| page[number] | `integer` | No | [Page number](../../../specification/pagination.html#api-pagination). |
| page[size] | `integer` | No | [Page size](../../../specification/pagination.html#api-pagination). Pagination defaults to `50` records per page. The maximum is `100`. |

### Filters

| Filter Name | Type | Allow Blank | Allow Array | Filters by: |
| --- | --- | --- | --- | --- |
| id | `string` | No | Yes | The DID history UUID. |
| did\_number | `string` | No | No | The DID number. |
| action | `string` | No | No | The action value. |
| method | `string` | No | No | The method value. |
| created\_at\_gteq | `string` | No | No | Records created on or after the specified date and time. |
| created\_at\_lteq | `string` | No | No | Records created on or before the specified date and time. |

### Available Action Values

| Value | Description |
| --- | --- |
| assigned | DID assignment event. |
| renewed | DID renewal event. |
| canceled | DID cancellation event. |
| removed | DID release or removal event. |
| billing\_cycles\_count\_changed | Billing cycles count change event. |
| restored | DID restoration event. |

Note

The `meta.from` and `meta.to` values are returned only for `billing_cycles_count_changed` records.

### Available Method Values

| Value | Description |
| --- | --- |
| system | Action performed by the system. |
| api2 | Action performed through API v2. |
| api3 | Action performed through API v3. |
| staff | Action performed by staff. |
| user\_panel | Action performed from the user panel. |
| mcp | Changed through the MCP server. |

### Sorting

| Value | Sorts by: |
| --- | --- |
| created\_at | Creation timestamp |

## Examples

Simple RequestFilter by Timeframe

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/did_history HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET https://api.didww.com/v3/did_history -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": [
 6        {
 7            "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
 8            "type": "did_history",
 9            "attributes": {
10                "did_number": "437xxxxxxxxx",
11                "action": "removed",
12                "method": "api3",
13                "created_at": "2026-03-06T15:11:00.326Z"
14            }
15        },
16        {
17            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
18            "type": "did_history",
19            "attributes": {
20                "did_number": "437xxxxxxxxx",
21                "action": "renewed",
22                "method": "api2",
23                "created_at": "2026-04-16T11:30:00.000Z"
24            }
25        },
26        {
27            "id": "9e3b65e9-fdc4-1810-9e93-b7127ab59ee6",
28            "type": "did_history",
29            "attributes": {
30                "did_number": "437xxxxxxxxx",
31                "action": "billing_cycles_count_changed",
32                "method": "staff",
33                "created_at": "2026-04-03T17:42:45.728Z"
34            },
35            "meta": {
36                "from": "empty",
37                "to": "5"
38            }
39        }
40    ],
41    "links": {
42        "first": "https://api.didww.com/v3/did_history?page%5Bnumber%5D=1&page%5Bsize%5D=50",
43        "last": "https://api.didww.com/v3/did_history?page%5Bnumber%5D=1&page%5Bsize%5D=50"
44    },
45    "meta": {
46        "total_records": 3,
47        "api_version": "2026-11-19"
48    }
49}
```

[[DIDWW-API-EXAMPLE-END]]

[[DIDWW-API-EXAMPLE-START]]

http

```
1GET /v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]
```

curl

```
1curl -i -X GET 'https://api.didww.com/v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z' -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"
```

response

```
 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": [
 6        {
 7            "id": "9e3b65e9-fdc4-1810-9e93-b7127ab6b976",
 8            "type": "did_history",
 9            "attributes": {
10                "did_number": "437xxxxxxxxx",
11                "action": "removed",
12                "method": "api3",
13                "created_at": "2026-03-06T15:11:00.326Z"
14            }
15        },
16        {
17            "id": "9e3b65e9-fdc4-1810-9e93-b7127ab59ee6",
18            "type": "did_history",
19            "attributes": {
20                "did_number": "437xxxxxxxxx",
21                "action": "billing_cycles_count_changed",
22                "method": "staff",
23                "created_at": "2026-04-03T17:42:45.728Z"
24            },
25            "meta": {
26                "from": "empty",
27                "to": "5"
28            }
29        }
30    ],
31    "links": {
32        "first": "https://api.didww.com/v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z&page%5Bnumber%5D=1&page%5Bsize%5D=50",
33        "last": "https://api.didww.com/v3/did_history?filter%5Bcreated_at_gteq%5D=2026-03-01T00%3A00%3A00Z&filter%5Bcreated_at_lteq%5D=2026-04-01T00%3A00%3A00Z&page%5Bnumber%5D=1&page%5Bsize%5D=50"
34    },
35    "meta": {
36        "total_records": 2,
37        "api_version": "2026-11-19"
38    }
39}
```

[[DIDWW-API-EXAMPLE-END]]

## Other Responses

| Code | Success | Description |
| --- | --- | --- |
| 400 | No | Invalid filter value, invalid sort criteria, or the `created_at` filter date is outside the last 90 days. |
| 401 | No | [Unauthorized](../../authentication.html#authentication-v35) |
| 429 | No | The request budget of the account for the current window is spent (`too_many_requests`). `Retry-After` gives the number of seconds to wait. |
