# Recently used models

Track which AI models your API key has recently used to provide a better user experience.

## Overview

The Recently Used Models feature automatically tracks which models each API key uses, allowing you to display recently accessed models in your UI for quick selection.

## How It Works

- **Automatic Tracking**: Every time you make a request with a specific model, the system records the timestamp
- **Per API Key**: Each API key has its own usage history
- **Timestamp Updates**: Using the same model again updates the timestamp to the current time
- **Usage Counter**: Tracks how many times each model has been used


#### Query Parameters

**`include_recent_usage`** boolean optional · Defaults to `false`

Include `last_used_at` timestamp for each model.

**`ui_models_only`** boolean optional · Defaults to `false`

Filter to UI-visible models only.

**`include_capabilities`** boolean optional · Defaults to `true`

Include model capabilities.

**`include_details`** boolean optional · Defaults to `false`

Include detailed model information.

## Returns

A list of [Model objects](/docs/api-reference/objects/model-object) with `last_used_at` timestamps.

**Fields**:

- `last_used_at` (string | null): ISO 8601 timestamp of when this model was last used by your API key. `null` if never used.


## Important Notes

- **API Key Only**: This feature only works with API key authentication. Bearer token authentication does not track model usage.
- **Per Key Tracking**: Each API key maintains its own usage history. Different keys will have different recently used models.
- **Automatic Updates**: You don't need to do anything special - just use models normally and the tracking happens automatically.
- **No Performance Impact**: Tracking is done asynchronously and won't slow down your requests.
- **Privacy**: Usage data is only visible to the API key that generated it.


## Use Cases

1. **Quick Model Selection**: Show users their most frequently used models at the top of dropdowns
2. **Personalized Experience**: Customize the UI based on user preferences
3. **Model Switching**: Make it easy to switch between recently used models
4. **Usage Analytics**: Track which models are most popular for your use case


Basic Request

```bash cURL
curl "https://api.aitronos.com/v1/models?include_recent_usage=true" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"X-API-Key": api_key},
    params={"include_recent_usage": True}
)

models = response.json()
print(f"Found {models['total_count']} models")
for model in models['models']:
    if model.get('last_used_at'):
        print(f"- {model['name']}: Last used {model['last_used_at']}")
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch(
  "https://api.aitronos.com/v1/models?include_recent_usage=true",
  {
    headers: {
      "X-API-Key": apiKey,
    },
  }
);

const models = await response.json();
console.log(`Found ${models.total_count} models`);
models.models.forEach((model) => {
  if (model.last_used_at) {
    console.log(`- ${model.name}: Last used ${model.last_used_at}`);
  }
});
```

**Response:**


```json 200 OK
{
  "models": [
    {
      "id": "mdl_09adacc3e5d3",
      "key": "gpt-4o",
      "name": "GPT-4o",
      "description": "Most advanced multimodal model",
      "last_used_at": "2026-01-16T08:15:42Z",
      "is_visible_in_ui": true,
      "availability_status": "general_availability",
      "recommended_for": ["general_purpose", "reasoning"],
      "capabilities": ["text_generation", "vision", "tool_calling"]
    },
    {
      "id": "mdl_abc123def456",
      "key": "claude-sonnet-4.5",
      "name": "Claude Sonnet 4.5",
      "last_used_at": "2026-01-16T08:14:30Z",
      "is_visible_in_ui": true,
      "capabilities": ["text_generation", "vision"]
    },
    {
      "id": "mdl_xyz789ghi012",
      "key": "ftg-3.0-speed",
      "name": "FTG 3.0 Speed",
      "last_used_at": null,
      "is_visible_in_ui": true,
      "capabilities": ["text_generation"]
    }
  ],
  "total_count": 3
}
```

Filter Recently Used

```bash cURL
curl "https://api.aitronos.com/v1/models?include_recent_usage=true" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python
import os
import requests
from datetime import datetime

api_key = os.environ["FREDDY_API_KEY"]

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"X-API-Key": api_key},
    params={"include_recent_usage": True}
)

data = response.json()

# Filter and sort by recently used
recently_used = [
    model for model in data['models']
    if model.get('last_used_at') is not None
]

recently_used.sort(
    key=lambda m: datetime.fromisoformat(m['last_used_at'].replace('Z', '+00:00')),
    reverse=True
)

# Top 5 most recent
top_5 = recently_used[:5]

print("Recently used models:")
for model in top_5:
    print(f"- {model['name']} ({model['key']})")
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch(
  "https://api.aitronos.com/v1/models?include_recent_usage=true",
  {
    headers: {
      "X-API-Key": apiKey,
    },
  }
);

const data = await response.json();

// Filter and sort by recently used
const recentlyUsed = data.models
  .filter((model) => model.last_used_at !== null)
  .sort((a, b) => new Date(b.last_used_at) - new Date(a.last_used_at))
  .slice(0, 5); // Top 5 most recent

console.log("Recently used models:");
recentlyUsed.forEach((model) => {
  console.log(`- ${model.name} (${model.key})`);
});
```

**Response:**


```json 200 OK
{
  "models": [
    {
      "id": "mdl_09adacc3e5d3",
      "key": "gpt-4o",
      "name": "GPT-4o",
      "last_used_at": "2026-01-16T08:15:42Z",
      "is_visible_in_ui": true,
      "capabilities": ["text_generation", "vision", "tool_calling"]
    },
    {
      "id": "mdl_abc123def456",
      "key": "claude-sonnet-4.5",
      "name": "Claude Sonnet 4.5",
      "last_used_at": "2026-01-16T08:14:30Z",
      "is_visible_in_ui": true,
      "capabilities": ["text_generation", "vision"]
    }
  ],
  "total_count": 2
}
```

UI Integration

```javascript JavaScript
// Fetch models with recent usage
const response = await fetch(
  "https://api.aitronos.com/v1/models?include_recent_usage=true",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY,
    },
  }
);

const data = await response.json();

// Separate recently used from all models
const recentlyUsed = data.models
  .filter((model) => model.last_used_at !== null)
  .sort((a, b) => new Date(b.last_used_at) - new Date(a.last_used_at))
  .slice(0, 5);

const allModels = data.models;

// Build model selector
const modelSelector = document.getElementById("model-selector");

// Add "Recently Used" section
if (recentlyUsed.length > 0) {
  const recentSection = document.createElement("optgroup");
  recentSection.label = "Recently Used";

  recentlyUsed.forEach((model) => {
    const option = document.createElement("option");
    option.value = model.key;
    option.textContent = model.name;
    recentSection.appendChild(option);
  });

  modelSelector.appendChild(recentSection);
}

// Add all other models
const allModelsSection = document.createElement("optgroup");
allModelsSection.label = "All Models";

allModels.forEach((model) => {
  const option = document.createElement("option");
  option.value = model.key;
  option.textContent = model.name;
  allModelsSection.appendChild(option);
});

modelSelector.appendChild(allModelsSection);
```


```python Python - Flask
import os
import requests
from flask import render_template

api_key = os.environ["FREDDY_API_KEY"]

@app.route('/chat')
def chat_page():
    # Fetch models with recent usage
    response = requests.get(
        "https://api.aitronos.com/v1/models",
        headers={"X-API-Key": api_key},
        params={"include_recent_usage": True}
    )

    data = response.json()

    # Separate recently used models
    recently_used = [
        model for model in data['models']
        if model.get('last_used_at') is not None
    ]

    recently_used.sort(
        key=lambda m: m['last_used_at'],
        reverse=True
    )

    return render_template(
        'chat.html',
        recently_used=recently_used[:5],
        all_models=data['models']
    )
```


```html HTML Template
<select id="model-selector" name="model">
  <!-- Recently Used Section -->
  <optgroup label="Recently Used">
    <option value="gpt-4o">GPT-4o</option>
    <option value="claude-sonnet-4.5">Claude Sonnet 4.5</option>
  </optgroup>

  <!-- All Models Section -->
  <optgroup label="All Models">
    <option value="gpt-4o">GPT-4o</option>
    <option value="claude-sonnet-4.5">Claude Sonnet 4.5</option>
    <option value="ftg-3.0-speed">FTG 3.0 Speed</option>
  </optgroup>
</select>
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-01-16T10:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource.",
    "system_message": "Insufficient permissions for organization",
    "type": "authorization_error",
    "status": 403,
    "trace_id": "req_def456uvw",
    "timestamp": "2026-01-16T10:30:00Z"
  }
}
```


```json 429 Rate Limit
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "system_message": "Rate limit exceeded for endpoint",
    "type": "rate_limit_error",
    "status": 429,
    "trace_id": "req_ghi789rst",
    "timestamp": "2026-01-16T10:30:00Z"
  }
}
```