0
# Models API
1

2
The Models API provides access to information about available Claude models, allowing you to retrieve model details, list available models, and resolve model aliases to specific model IDs.
3

4
## Capabilities
5

6
### Retrieving Model Information
7

8
Get detailed information about a specific model by its ID or alias. The Models API can resolve aliases like "claude-3-5-sonnet-latest" to specific version identifiers and return model metadata.
9

10
```python { .api }
11
def retrieve(
12
    model_id: str,
13
    *,
14
    betas: List[AnthropicBetaParam] | Omit = omit,
15
    extra_headers: Headers | None = None,
16
    extra_query: Query | None = None,
17
    extra_body: Body | None = None,
18
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
19
) -> ModelInfo:
20
    """
21
    Get a specific model.
22

23
    The Models API response can be used to determine information about a specific
24
    model or resolve a model alias to a model ID.
25

26
    Parameters:
27
        model_id: Model identifier or alias (e.g., "claude-3-5-sonnet-20241022" or
28
                 "claude-3-5-sonnet-latest")
29
        betas: Optional header to specify the beta version(s) you want to use
30
        extra_headers: Send extra headers
31
        extra_query: Add additional query parameters to the request
32
        extra_body: Add additional JSON properties to the request
33
        timeout: Override the client-level default timeout for this request, in seconds
34

35
    Returns:
36
        ModelInfo: Model information including ID, display name, and creation timestamp
37

38
    Raises:
39
        ValueError: If model_id is empty
40
        NotFoundError: If the model_id does not exist
41
        AuthenticationError: If API key is invalid
42
        RateLimitError: If rate limit is exceeded
43
    """
44
```
45

46
**Sync Example:**
47

48
```python
49
import anthropic
50

51
client = anthropic.Anthropic(api_key="your-api-key")
52

53
# Retrieve specific model info by ID
54
model = client.models.retrieve("claude-3-5-sonnet-20241022")
55
print(f"Model: {model.display_name}")
56
print(f"ID: {model.id}")
57
print(f"Created: {model.created_at}")
58

59
# Resolve a model alias to its ID
60
latest_sonnet = client.models.retrieve("claude-3-5-sonnet-latest")
61
print(f"Latest Sonnet ID: {latest_sonnet.id}")
62
```
63

64
**Async Example:**
65

66
```python
67
import anthropic
68
import asyncio
69

70
async def get_model_info():
71
    client = anthropic.AsyncAnthropic(api_key="your-api-key")
72

73
    model = await client.models.retrieve("claude-3-5-sonnet-20241022")
74
    print(f"Model: {model.display_name}")
75
    print(f"ID: {model.id}")
76

77
    await client.close()
78

79
asyncio.run(get_model_info())
80
```
81

82
### Listing Available Models
83

84
List all available models with pagination support. Models are returned in reverse chronological order, with the most recently released models appearing first.
85

86
```python { .api }
87
def list(
88
    *,
89
    after_id: str | Omit = omit,
90
    before_id: str | Omit = omit,
91
    limit: int | Omit = omit,
92
    betas: List[AnthropicBetaParam] | Omit = omit,
93
    extra_headers: Headers | None = None,
94
    extra_query: Query | None = None,
95
    extra_body: Body | None = None,
96
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
97
) -> SyncPage[ModelInfo]:
98
    """
99
    List available models.
100

101
    The Models API response can be used to determine which models are available for
102
    use in the API. More recently released models are listed first.
103

104
    Parameters:
105
        after_id: ID of the object to use as a cursor for pagination. When provided,
106
                 returns the page of results immediately after this object
107
        before_id: ID of the object to use as a cursor for pagination. When provided,
108
                  returns the page of results immediately before this object
109
        limit: Number of items to return per page. Defaults to 20. Ranges from 1 to 1000
110
        betas: Optional header to specify the beta version(s) you want to use
111
        extra_headers: Send extra headers
112
        extra_query: Add additional query parameters to the request
113
        extra_body: Add additional JSON properties to the request
114
        timeout: Override the client-level default timeout for this request, in seconds
115

116
    Returns:
117
        SyncPage[ModelInfo]: Paginated list of models
118

119
    Raises:
120
        AuthenticationError: If API key is invalid
121
        RateLimitError: If rate limit is exceeded
122
    """
123
```
124

125
**Sync Example:**
126

127
```python
128
import anthropic
129

130
client = anthropic.Anthropic(api_key="your-api-key")
131

132
# List all available models
133
models = client.models.list()
134

135
for model in models:
136
    print(f"{model.display_name} - {model.id}")
137

138
# List with pagination
139
first_page = client.models.list(limit=10)
140
print(f"First page has {len(list(first_page))} models")
141

142
# Get next page using the last model ID from the first page
143
models_list = list(client.models.list(limit=10))
144
if models_list:
145
    last_id = models_list[-1].id
146
    second_page = client.models.list(after_id=last_id, limit=10)
147
    print(f"Second page has {len(list(second_page))} models")
148
```
149

150
**Async Example:**
151

152
```python
153
import anthropic
154
import asyncio
155

156
async def list_models():
157
    client = anthropic.AsyncAnthropic(api_key="your-api-key")
158

159
    # List all available models
160
    models = await client.models.list()
161

162
    async for model in models:
163
        print(f"{model.display_name} - {model.id}")
164

165
    await client.close()
166

167
asyncio.run(list_models())
168
```
169

170
**Advanced Pagination Example:**
171

172
```python
173
import anthropic
174

175
client = anthropic.Anthropic(api_key="your-api-key")
176

177
# Iterate through all models with automatic pagination
178
all_models = []
179
page = client.models.list(limit=50)
180

181
for model in page:
182
    all_models.append(model)
183
    print(f"Loaded: {model.display_name}")
184

185
print(f"Total models: {len(all_models)}")
186

187
# Filter models by criteria
188
sonnet_models = [m for m in all_models if "sonnet" in m.id.lower()]
189
print(f"Found {len(sonnet_models)} Sonnet models")
190
```
191

192
## Resource Classes
193

194
### Models (Sync)
195

196
```python { .api }
197
class Models(SyncAPIResource):
198
    """
199
    Synchronous resource for managing model information.
200

201
    Access via client.models
202
    """
203

204
    def retrieve(
205
        self,
206
        model_id: str,
207
        *,
208
        betas: List[AnthropicBetaParam] | Omit = omit,
209
        extra_headers: Headers | None = None,
210
        extra_query: Query | None = None,
211
        extra_body: Body | None = None,
212
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
213
    ) -> ModelInfo: ...
214

215
    def list(
216
        self,
217
        *,
218
        after_id: str | Omit = omit,
219
        before_id: str | Omit = omit,
220
        limit: int | Omit = omit,
221
        betas: List[AnthropicBetaParam] | Omit = omit,
222
        extra_headers: Headers | None = None,
223
        extra_query: Query | None = None,
224
        extra_body: Body | None = None,
225
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
226
    ) -> SyncPage[ModelInfo]: ...
227

228
    @cached_property
229
    def with_raw_response(self) -> ModelsWithRawResponse:
230
        """
231
        Property to access raw response wrapper.
232
        Returns the raw httpx.Response object instead of the parsed content.
233
        """
234

235
    @cached_property
236
    def with_streaming_response(self) -> ModelsWithStreamingResponse:
237
        """
238
        Property to access streaming response wrapper.
239
        Doesn't eagerly read the response body.
240
        """
241
```
242

243
### AsyncModels (Async)
244

245
```python { .api }
246
class AsyncModels(AsyncAPIResource):
247
    """
248
    Asynchronous resource for managing model information.
249

250
    Access via client.models
251
    """
252

253
    async def retrieve(
254
        self,
255
        model_id: str,
256
        *,
257
        betas: List[AnthropicBetaParam] | Omit = omit,
258
        extra_headers: Headers | None = None,
259
        extra_query: Query | None = None,
260
        extra_body: Body | None = None,
261
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
262
    ) -> ModelInfo: ...
263

264
    def list(
265
        self,
266
        *,
267
        after_id: str | Omit = omit,
268
        before_id: str | Omit = omit,
269
        limit: int | Omit = omit,
270
        betas: List[AnthropicBetaParam] | Omit = omit,
271
        extra_headers: Headers | None = None,
272
        extra_query: Query | None = None,
273
        extra_body: Body | None = None,
274
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
275
    ) -> AsyncPaginator[ModelInfo, AsyncPage[ModelInfo]]: ...
276

277
    @cached_property
278
    def with_raw_response(self) -> AsyncModelsWithRawResponse:
279
        """
280
        Property to access raw response wrapper.
281
        Returns the raw httpx.Response object instead of the parsed content.
282
        """
283

284
    @cached_property
285
    def with_streaming_response(self) -> AsyncModelsWithStreamingResponse:
286
        """
287
        Property to access streaming response wrapper.
288
        Doesn't eagerly read the response body.
289
        """
290
```
291

292
## Types
293

294
### ModelInfo
295

296
```python { .api }
297
class ModelInfo(BaseModel):
298
    """
299
    Information about a Claude model.
300

301
    Contains metadata about the model including its identifier, display name,
302
    and creation timestamp.
303
    """
304

305
    id: str
306
    """Model ID (e.g., "claude-3-5-sonnet-20241022")"""
307

308
    type: Literal["model"]
309
    """Type identifier, always "model" """
310

311
    display_name: str
312
    """Human-readable name (e.g., "Claude 3.5 Sonnet")"""
313

314
    created_at: datetime
315
    """Creation timestamp"""
316
```
317

318
### AnthropicBetaParam
319

320
```python { .api }
321
from typing import Union
322

323
AnthropicBetaParam = Union[
324
    str,
325
    Literal[
326
        "message-batches-2024-09-24",
327
        "prompt-caching-2024-07-31",
328
        "computer-use-2024-10-22",
329
        "pdfs-2024-09-25",
330
        "token-counting-2024-11-01",
331
        # Additional beta identifiers...
332
    ]
333
]
334
"""
335
Beta version identifier for accessing beta features.
336

337
Can be a string or specific beta version literal. Pass as a list to the betas parameter.
338
"""
339
```
340

341
### Pagination Types
342

343
```python { .api }
344
class SyncPage(Generic[T]):
345
    """
346
    Synchronous paginated response.
347

348
    Iterating over this object will automatically fetch additional pages as needed.
349
    """
350

351
    def __iter__(self) -> Iterator[T]:
352
        """Iterate over items across all pages"""
353

354
    def has_next_page(self) -> bool:
355
        """Check if there are more pages available"""
356

357

358
class AsyncPage(Generic[T]):
359
    """
360
    Asynchronous paginated response.
361

362
    Async iterating over this object will automatically fetch additional pages as needed.
363
    """
364

365
    def __aiter__(self) -> AsyncIterator[T]:
366
        """Async iterate over items across all pages"""
367

368
    async def has_next_page(self) -> bool:
369
        """Check if there are more pages available"""
370

371

372
class AsyncPaginator(Generic[T, PageT]):
373
    """
374
    Asynchronous paginator for AsyncModels.list()
375

376
    Returns an async iterable that fetches pages automatically.
377
    """
378

379
    def __aiter__(self) -> AsyncIterator[T]:
380
        """Async iterate over all items"""
381
```
382

383
## Response Wrappers
384

385
The Models resource provides response wrapper variants for accessing raw HTTP responses:
386

387
### ModelsWithRawResponse
388

389
```python { .api }
390
class ModelsWithRawResponse:
391
    """
392
    Synchronous raw response wrapper for Models resource.
393

394
    Access via client.models.with_raw_response
395
    """
396

397
    def retrieve(
398
        self,
399
        model_id: str,
400
        *,
401
        betas: List[AnthropicBetaParam] | Omit = omit,
402
        extra_headers: Headers | None = None,
403
        extra_query: Query | None = None,
404
        extra_body: Body | None = None,
405
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
406
    ) -> APIResponse[ModelInfo]:
407
        """Returns APIResponse wrapper with parsed data and raw response"""
408

409
    def list(
410
        self,
411
        *,
412
        after_id: str | Omit = omit,
413
        before_id: str | Omit = omit,
414
        limit: int | Omit = omit,
415
        betas: List[AnthropicBetaParam] | Omit = omit,
416
        extra_headers: Headers | None = None,
417
        extra_query: Query | None = None,
418
        extra_body: Body | None = None,
419
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
420
    ) -> APIResponse[SyncPage[ModelInfo]]:
421
        """Returns APIResponse wrapper with parsed data and raw response"""
422
```
423

424
**Example:**
425

426
```python
427
import anthropic
428

429
client = anthropic.Anthropic(api_key="your-api-key")
430

431
# Access raw response
432
response = client.models.with_raw_response.retrieve("claude-3-5-sonnet-20241022")
433

434
# Access parsed model data
435
model = response.parse()
436
print(f"Model: {model.display_name}")
437

438
# Access raw HTTP response
439
print(f"Status Code: {response.status_code}")
440
print(f"Headers: {response.headers}")
441
print(f"Request ID: {response.headers.get('request-id')}")
442
```
443

444
### AsyncModelsWithRawResponse
445

446
```python { .api }
447
class AsyncModelsWithRawResponse:
448
    """
449
    Asynchronous raw response wrapper for Models resource.
450

451
    Access via client.models.with_raw_response
452
    """
453

454
    async def retrieve(
455
        self,
456
        model_id: str,
457
        *,
458
        betas: List[AnthropicBetaParam] | Omit = omit,
459
        extra_headers: Headers | None = None,
460
        extra_query: Query | None = None,
461
        extra_body: Body | None = None,
462
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
463
    ) -> AsyncAPIResponse[ModelInfo]:
464
        """Returns AsyncAPIResponse wrapper with parsed data and raw response"""
465

466
    def list(
467
        self,
468
        *,
469
        after_id: str | Omit = omit,
470
        before_id: str | Omit = omit,
471
        limit: int | Omit = omit,
472
        betas: List[AnthropicBetaParam] | Omit = omit,
473
        extra_headers: Headers | None = None,
474
        extra_query: Query | None = None,
475
        extra_body: Body | None = None,
476
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
477
    ) -> AsyncAPIResponse[AsyncPaginator[ModelInfo, AsyncPage[ModelInfo]]]:
478
        """Returns AsyncAPIResponse wrapper with parsed data and raw response"""
479
```
480

481
### ModelsWithStreamingResponse
482

483
```python { .api }
484
class ModelsWithStreamingResponse:
485
    """
486
    Synchronous streaming response wrapper for Models resource.
487

488
    Doesn't eagerly read the response body. Access via client.models.with_streaming_response
489
    """
490

491
    def retrieve(
492
        self,
493
        model_id: str,
494
        *,
495
        betas: List[AnthropicBetaParam] | Omit = omit,
496
        extra_headers: Headers | None = None,
497
        extra_query: Query | None = None,
498
        extra_body: Body | None = None,
499
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
500
    ) -> APIResponse[ModelInfo]:
501
        """Returns APIResponse without eagerly reading response body"""
502

503
    def list(
504
        self,
505
        *,
506
        after_id: str | Omit = omit,
507
        before_id: str | Omit = omit,
508
        limit: int | Omit = omit,
509
        betas: List[AnthropicBetaParam] | Omit = omit,
510
        extra_headers: Headers | None = None,
511
        extra_query: Query | None = None,
512
        extra_body: Body | None = None,
513
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
514
    ) -> APIResponse[SyncPage[ModelInfo]]:
515
        """Returns APIResponse without eagerly reading response body"""
516
```
517

518
### AsyncModelsWithStreamingResponse
519

520
```python { .api }
521
class AsyncModelsWithStreamingResponse:
522
    """
523
    Asynchronous streaming response wrapper for Models resource.
524

525
    Doesn't eagerly read the response body. Access via client.models.with_streaming_response
526
    """
527

528
    async def retrieve(
529
        self,
530
        model_id: str,
531
        *,
532
        betas: List[AnthropicBetaParam] | Omit = omit,
533
        extra_headers: Headers | None = None,
534
        extra_query: Query | None = None,
535
        extra_body: Body | None = None,
536
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
537
    ) -> AsyncAPIResponse[ModelInfo]:
538
        """Returns AsyncAPIResponse without eagerly reading response body"""
539

540
    def list(
541
        self,
542
        *,
543
        after_id: str | Omit = omit,
544
        before_id: str | Omit = omit,
545
        limit: int | Omit = omit,
546
        betas: List[AnthropicBetaParam] | Omit = omit,
547
        extra_headers: Headers | None = None,
548
        extra_query: Query | None = None,
549
        extra_body: Body | None = None,
550
        timeout: float | httpx.Timeout | None | NotGiven = not_given,
551
    ) -> AsyncAPIResponse[AsyncPaginator[ModelInfo, AsyncPage[ModelInfo]]]:
552
        """Returns AsyncAPIResponse without eagerly reading response body"""
553
```
554

555
## Usage Patterns
556

557
### Selecting Models Dynamically
558

559
Use the Models API to dynamically select appropriate models for your application:
560

561
```python
562
import anthropic
563

564
client = anthropic.Anthropic(api_key="your-api-key")
565

566
# Get list of available models
567
models = list(client.models.list())
568

569
# Find the latest Sonnet model
570
sonnet_models = [m for m in models if "sonnet" in m.id.lower()]
571
latest_sonnet = sonnet_models[0] if sonnet_models else None
572

573
if latest_sonnet:
574
    print(f"Using: {latest_sonnet.display_name}")
575

576
    # Use the model for message creation
577
    message = client.messages.create(
578
        model=latest_sonnet.id,
579
        max_tokens=1024,
580
        messages=[{"role": "user", "content": "Hello!"}]
581
    )
582
    print(message.content[0].text)
583
```
584

585
### Resolving Model Aliases
586

587
Model aliases allow you to use shorthand names that automatically resolve to specific model versions:
588

589
```python
590
import anthropic
591

592
client = anthropic.Anthropic(api_key="your-api-key")
593

594
# Resolve alias to actual model ID
595
alias = "claude-3-5-sonnet-latest"
596
model_info = client.models.retrieve(alias)
597

598
print(f"Alias '{alias}' resolves to:")
599
print(f"  ID: {model_info.id}")
600
print(f"  Name: {model_info.display_name}")
601
print(f"  Created: {model_info.created_at}")
602

603
# Use the resolved ID for API calls
604
message = client.messages.create(
605
    model=model_info.id,
606
    max_tokens=1024,
607
    messages=[{"role": "user", "content": "What is your model version?"}]
608
)
609
print(message.content[0].text)
610
```
611

612
### Caching Model Information
613

614
Cache model information to reduce API calls:
615

616
```python
617
import anthropic
618
from datetime import datetime, timedelta
619

620
class ModelCache:
621
    def __init__(self, client):
622
        self.client = client
623
        self.cache = {}
624
        self.cache_duration = timedelta(hours=24)
625

626
    def get_model(self, model_id):
627
        """Get model from cache or fetch from API"""
628
        now = datetime.now()
629

630
        if model_id in self.cache:
631
            cached_model, cached_time = self.cache[model_id]
632
            if now - cached_time < self.cache_duration:
633
                return cached_model
634

635
        # Fetch from API and cache
636
        model = self.client.models.retrieve(model_id)
637
        self.cache[model_id] = (model, now)
638
        return model
639

640
    def get_all_models(self):
641
        """Get all models, refreshing cache if needed"""
642
        cache_key = "__all__"
643
        now = datetime.now()
644

645
        if cache_key in self.cache:
646
            cached_models, cached_time = self.cache[cache_key]
647
            if now - cached_time < self.cache_duration:
648
                return cached_models
649

650
        # Fetch from API and cache
651
        models = list(self.client.models.list())
652
        self.cache[cache_key] = (models, now)
653
        return models
654

655
# Usage
656
client = anthropic.Anthropic(api_key="your-api-key")
657
cache = ModelCache(client)
658

659
# First call hits API
660
model1 = cache.get_model("claude-3-5-sonnet-20241022")
661
print(f"Fetched: {model1.display_name}")
662

663
# Second call uses cache
664
model2 = cache.get_model("claude-3-5-sonnet-20241022")
665
print(f"Cached: {model2.display_name}")
666
```
667

668
### Using Beta Features
669

670
Access beta features by passing beta version identifiers:
671

672
```python
673
import anthropic
674

675
client = anthropic.Anthropic(api_key="your-api-key")
676

677
# Retrieve model info with beta features enabled
678
model = client.models.retrieve(
679
    "claude-3-5-sonnet-20241022",
680
    betas=["message-batches-2024-09-24", "prompt-caching-2024-07-31"]
681
)
682

683
print(f"Model: {model.display_name}")
684
print(f"ID: {model.id}")
685

686
# List models with beta features
687
models = client.models.list(
688
    betas=["message-batches-2024-09-24"]
689
)
690

691
for model in models:
692
    print(f"{model.display_name} - {model.id}")
693
```
694

695
## Common Imports
696

697
```python
698
from anthropic import Anthropic, AsyncAnthropic
699
from anthropic.types import ModelInfo
700
from anthropic.pagination import SyncPage, AsyncPage, AsyncPaginator
701
from anthropic.types.anthropic_beta_param import AnthropicBetaParam
702
```
703