${current}/${required} (${progress.remaining} remaining)
`;
}
// Usage
const progress = await getAchievementProgress('alice.zks', 'defi-pioneer');
const progressBar = createProgressBar(progress);
document.getElementById('progress-container').innerHTML = progressBar;
```
### 2. Milestone Tracking
Show progress milestones:
```javascript theme={null}
function displayMilestones(progress) {
console.log(`\nšÆ Milestones for ${progress.achievement.title}:`);
progress.milestones.forEach((milestone, index) => {
const status = milestone.reached ? 'ā
' : 'ā³';
const reachedText = milestone.reached ?
` (reached ${new Date(milestone.reachedAt).toLocaleDateString()})` : '';
console.log(`${status} Milestone ${index + 1}: ${milestone.value} protocols (${milestone.percentage}%)${reachedText}`);
});
}
```
### 3. Progress History Chart
Visualize progress over time:
```javascript theme={null}
async function createProgressChart(identity, achievementId) {
const data = await getAchievementProgress(identity, achievementId, {
includeHistory: true,
timeframe: '30d'
});
const chartData = data.history.map(point => ({
x: new Date(point.timestamp),
y: point.percentage
}));
// Use your preferred charting library
const chart = new Chart('progress-chart', {
type: 'line',
data: {
datasets: [{
label: 'Progress %',
data: chartData,
borderColor: '#4F46E5',
backgroundColor: 'rgba(79, 70, 229, 0.1)'
}]
},
options: {
scales: {
x: { type: 'time' },
y: { min: 0, max: 100 }
}
}
});
}
```
### 4. Achievement Suggestions
Show helpful suggestions:
```javascript theme={null}
function displaySuggestions(progress) {
if (progress.suggestions && progress.suggestions.length > 0) {
console.log(`\nš” Suggestions to earn ${progress.achievement.title}:`);
progress.suggestions.forEach((suggestion, index) => {
console.log(`${index + 1}. ${suggestion}`);
});
}
}
```
### 5. Time Estimation
Show estimated completion time:
```javascript theme={null}
function displayTimeEstimate(progress) {
if (progress.estimatedTime) {
const { days, confidence, basedOn } = progress.estimatedTime;
console.log(`\nā° Estimated completion: ${days} days`);
console.log(`Confidence: ${confidence}`);
console.log(`Based on: ${basedOn}`);
if (days <= 7) {
console.log('š You\'re close to earning this achievement!');
} else if (days <= 30) {
console.log('š Good progress! Keep it up!');
} else {
console.log('šāāļø This will take some time, but you\'re making progress!');
}
}
}
```
## Best Practices
### 1. Cache Progress Data
Progress data changes frequently but can be cached briefly:
```javascript theme={null}
let progressCache = new Map();
const CACHE_TTL = 2 * 60 * 1000; // 2 minutes
async function getCachedProgress(identity, achievementId, options = {}) {
const cacheKey = `${identity}-${achievementId}-${JSON.stringify(options)}`;
const cached = progressCache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const data = await getAchievementProgress(identity, achievementId, options);
progressCache.set(cacheKey, {
data,
timestamp: Date.now()
});
return data;
}
```
### 2. Real-time Updates
Subscribe to progress updates:
```javascript theme={null}
function subscribeToProgressUpdates(identity, achievementId, callback) {
const ws = new WebSocket(`wss://api.onzks.com/v1/achievements/${identity}/progress/${achievementId}/subscribe`);
ws.onmessage = (event) => {
const update = JSON.parse(event.data);
callback(update);
};
return () => ws.close();
}
// Usage
const unsubscribe = subscribeToProgressUpdates('alice.zks', 'defi-pioneer', (update) => {
console.log(`Progress updated: ${update.percentage}%`);
updateProgressBar(update);
});
```
### 3. Batch Progress Queries
Get progress for multiple achievements:
```javascript theme={null}
async function getMultipleProgress(identity, achievementIds) {
const promises = achievementIds.map(id =>
getAchievementProgress(identity, id)
);
const results = await Promise.all(promises);
return results.reduce((acc, result) => {
acc[result.achievement.id] = result;
return acc;
}, {});
}
// Usage
const progress = await getMultipleProgress('alice.zks', ['defi-pioneer', 'whale-trader', 'governance-guru']);
```
### 4. Progress Analytics
Analyze progress patterns:
```javascript theme={null}
function analyzeProgress(progress) {
const { current, required, percentage } = progress.progress;
const analysis = {
completionRate: percentage,
isOnTrack: percentage >= 50,
isClose: percentage >= 80,
isStalled: percentage < 10 && current > 0,
needsBoost: percentage < 25 && current > 0
};
return analysis;
}
```
## Related Endpoints
* [Get User Achievements](/api-reference/achievements/get-user-achievements) - All user achievements
* [List Achievements](/api-reference/achievements/list-achievements) - All available achievements
* [Claim Achievement](/api-reference/achievements/claim-achievement) - Claim an earned achievement
## Troubleshooting
### "Achievement not found"
**Cause**: Invalid achievement ID or achievement doesn't exist.
**Solution**:
* Verify the achievement ID is correct
* Check if the achievement is still active
* Use the list achievements endpoint to see available achievements
### "User not found"
**Cause**: Invalid identity or user doesn't exist.
**Solution**:
* Verify the identity format (ZKS ID or wallet address)
* Check if the user has any activity on the platform
### "No progress data"
**Cause**: User hasn't started working toward this achievement.
**Solution**:
* This is normal for new achievements
* Progress will appear once the user starts relevant activities
## Rate Limits
Progress requests are subject to rate limits:
* **Free tier**: 60 requests per minute
* **Starter tier**: 300 requests per minute
* **Professional tier**: 1,000 requests per minute
* **Enterprise tier**: Custom limits
Implement caching to reduce API calls.