Analytics API Reference
Access tag analytics, view statistics, and export metrics via the API.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/tags/{id}/analytics | Get tag analytics |
| GET | /v1/tags/{id}/analytics/views | Get view details |
| GET | /v1/tags/{id}/analytics/logs | Get access logs |
| GET | /v1/analytics/overview | Account overview |
| GET | /v1/analytics/export | Export analytics data |
Get Tag Analytics
Retrieve analytics for a specific tag.
Request
GET /v1/tags/{id}/analytics
Query Parameters
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date (YYYY-MM-DD) |
end_date | string | End date (YYYY-MM-DD) |
granularity | string | hour, day, week, month |
Example
curl "https://api.tagd-ai.com/v1/tags/abc123/analytics?start_date=2024-01-01&end_date=2024-01-31" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": {
"tag_id": "abc123",
"period": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"summary": {
"total_views": 1523,
"unique_views": 892,
"qr_scans": 756,
"direct_visits": 767,
"average_time_seconds": 45
},
"by_device": {
"mobile": 1089,
"desktop": 398,
"tablet": 36
},
"by_country": {
"US": 823,
"UK": 234,
"DE": 156,
"FR": 112,
"other": 198
},
"by_browser": {
"Chrome": 687,
"Safari": 512,
"Firefox": 189,
"Edge": 98,
"other": 37
},
"timeseries": [
{
"date": "2024-01-01",
"views": 48,
"unique": 32
},
{
"date": "2024-01-02",
"views": 52,
"unique": 38
}
]
}
}
Get View Details
Get detailed view information.
Request
GET /v1/tags/{id}/analytics/views
Query Parameters
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date |
end_date | string | End date |
limit | integer | Items per page |
offset | integer | Skip items |
Example
curl "https://api.tagd-ai.com/v1/tags/abc123/analytics/views?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": {
"views": [
{
"timestamp": "2024-01-15T14:32:18Z",
"source": "qr_scan",
"device": "mobile",
"browser": "Safari",
"os": "iOS",
"country": "US",
"region": "California",
"duration_seconds": 38
}
]
},
"pagination": {
"total": 1523,
"limit": 50,
"offset": 0,
"has_more": true
}
}
Get Access Logs
Retrieve detailed access logs (requires access logging enabled).
Request
GET /v1/tags/{id}/analytics/logs
Query Parameters
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date |
end_date | string | End date |
limit | integer | Items per page |
offset | integer | Skip items |
level | string | Log level: basic, detailed |
Example
curl "https://api.tagd-ai.com/v1/tags/abc123/analytics/logs?level=detailed" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": {
"logs": [
{
"id": "log_xyz123",
"timestamp": "2024-01-15T14:32:18Z",
"event": "view",
"source": "qr_scan",
"ip_address": "192.168.1.x",
"user_agent": "Mozilla/5.0...",
"device": {
"type": "mobile",
"os": "iOS 17.2",
"browser": "Safari 17"
},
"location": {
"country": "US",
"region": "California",
"city": "San Francisco"
},
"referrer": null,
"duration_seconds": 38
}
]
},
"pagination": {
"total": 1523,
"limit": 20,
"offset": 0,
"has_more": true
}
}
Account Overview
Get analytics across all your tags.
Request
GET /v1/analytics/overview
Query Parameters
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date |
end_date | string | End date |
Example
curl "https://api.tagd-ai.com/v1/analytics/overview?start_date=2024-01-01&end_date=2024-01-31" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"success": true,
"data": {
"period": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"totals": {
"views": 15234,
"unique_views": 8923,
"qr_scans": 7892,
"tags_created": 12,
"files_uploaded": 28
},
"top_tags": [
{
"id": "abc123",
"title": "Popular Tag",
"views": 2341
},
{
"id": "def456",
"title": "Another Tag",
"views": 1892
}
],
"by_day": [
{
"date": "2024-01-01",
"views": 523,
"scans": 312
}
]
}
}
Export Analytics
Export analytics data in various formats.
Request
GET /v1/analytics/export
Query Parameters
| Parameter | Type | Description |
|---|---|---|
start_date | string | Start date |
end_date | string | End date |
format | string | csv, json |
include | string | Comma-separated: views,logs,summary |
tag_ids | string | Comma-separated tag IDs (optional) |
Example
curl "https://api.tagd-ai.com/v1/analytics/export?start_date=2024-01-01&end_date=2024-01-31&format=csv&include=views,summary" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o analytics_export.csv
Response (CSV)
date,tag_id,tag_title,views,unique_views,qr_scans,direct_visits
2024-01-01,abc123,Product Tag,48,32,28,20
2024-01-02,abc123,Product Tag,52,38,31,21
Response (JSON)
{
"success": true,
"data": {
"export_date": "2024-01-31T23:59:59Z",
"period": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"rows": [...]
}
}
Real-Time Analytics (Enterprise)
Get real-time view data.
Request
GET /v1/tags/{id}/analytics/realtime
Response
{
"success": true,
"data": {
"current_viewers": 5,
"views_last_hour": 23,
"views_last_24h": 156,
"active_sessions": [
{
"started_at": "2024-01-15T14:30:00Z",
"device": "mobile",
"country": "US"
}
]
}
}
Analytics Retention
| Plan | History |
|---|---|
| Free | 7 days |
| Pro | 1 year |
| Enterprise | 3 years |
Error Responses
400 Bad Request
{
"success": false,
"error": {
"code": "invalid_date_range",
"message": "End date must be after start date"
}
}
403 Forbidden
{
"success": false,
"error": {
"code": "analytics_not_enabled",
"message": "Access logging is not enabled for this tag"
}
}