Get Analytics

Get Analytics

curl --request GET \
  --url https://api.example.com/analytics

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/analytics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/analytics"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/analytics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "period": {
    "period.start": "<string>",
    "period.end": "<string>"
  },
  "overview": {
    "overview.totalViews": 123,
    "overview.totalWatchTime": 123,
    "overview.subscribersGained": 123,
    "overview.averageViewDuration": 123
  },
  "topVideos": [
    {
      "topVideos[].videoId": "<string>",
      "topVideos[].title": "<string>",
      "topVideos[].views": 123,
      "topVideos[].engagement": 123
    }
  ],
  "demographics": {
    "demographics.topCountries": [
      {}
    ],
    "demographics.ageGroups": {},
    "demographics.gender": {}
  },
  "insights": [
    {
      "insights[].type": "<string>",
      "insights[].message": "<string>",
      "insights[].priority": "<string>"
    }
  ],
  "error": "<string>"
}

GET

analytics

Get Analytics

curl --request GET \
  --url https://api.example.com/analytics

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/analytics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/analytics"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/analytics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "period": {
    "period.start": "<string>",
    "period.end": "<string>"
  },
  "overview": {
    "overview.totalViews": 123,
    "overview.totalWatchTime": 123,
    "overview.subscribersGained": 123,
    "overview.averageViewDuration": 123
  },
  "topVideos": [
    {
      "topVideos[].videoId": "<string>",
      "topVideos[].title": "<string>",
      "topVideos[].views": 123,
      "topVideos[].engagement": 123
    }
  ],
  "demographics": {
    "demographics.topCountries": [
      {}
    ],
    "demographics.ageGroups": {},
    "demographics.gender": {}
  },
  "insights": [
    {
      "insights[].type": "<string>",
      "insights[].message": "<string>",
      "insights[].priority": "<string>"
    }
  ],
  "error": "<string>"
}

Endpoint

GET /analytics

Description

Retrieves recent analytics data from YouTube, including views, engagement metrics, audience insights, and performance trends. This data is collected and analyzed by the Analytics & Optimization Agent.

Request

No parameters required.

Headers

No special headers required.

Response

The response structure is determined by the Analytics & Optimization Agent’s getRecentAnalytics() method. Typical fields include:

object

Time period for the analytics data.

string

ISO 8601 start date.

string

ISO 8601 end date.

object

High-level performance metrics.

number

Total video views in the period.

number

Total watch time in minutes.

number

New subscribers in the period.

number

Average view duration in seconds.

array

Best performing videos in the period.

string

YouTube video ID.

string

Video title.

number

View count.

number

Engagement rate (likes, comments, shares).

object

Audience demographic information.

array

Top viewer countries.

object

Age distribution of viewers.

object

Gender distribution.

array

AI-generated insights and recommendations from the Analytics Agent.

string

Insight type: "trend", "recommendation", "alert", etc.

string

Human-readable insight description.

string

Priority level: "high", "medium", "low".

string

Error message if the request fails.

Example Request

curl http://localhost:3456/analytics

fetch('http://localhost:3456/analytics')
  .then(response => response.json())
  .then(data => {
    console.log('Total Views:', data.overview.totalViews);
    console.log('Top Video:', data.topVideos[0].title);
  });

import requests

response = requests.get('http://localhost:3456/analytics')
analytics = response.json()

print(f"Total Views: {analytics['overview']['totalViews']}")
print(f"Subscribers Gained: {analytics['overview']['subscribersGained']}")

for insight in analytics['insights']:
    print(f"💡 {insight['message']}")

Example Response

Success

{
  "period": {
    "start": "2026-02-05T00:00:00.000Z",
    "end": "2026-03-05T00:00:00.000Z"
  },
  "overview": {
    "totalViews": 125430,
    "totalWatchTime": 892340,
    "subscribersGained": 1245,
    "averageViewDuration": 425,
    "engagementRate": 8.3
  },
  "topVideos": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Master React Hooks in 10 Minutes",
      "views": 45230,
      "engagement": 12.5,
      "publishedAt": "2026-02-20T14:00:00.000Z"
    },
    {
      "videoId": "jNQXAC9IVRw",
      "title": "10 Python Tips Every Developer Should Know",
      "views": 38920,
      "engagement": 10.8,
      "publishedAt": "2026-02-27T14:00:00.000Z"
    }
  ],
  "demographics": {
    "topCountries": [
      { "country": "US", "percentage": 42.3 },
      { "country": "IN", "percentage": 18.7 },
      { "country": "GB", "percentage": 9.2 }
    ],
    "ageGroups": {
      "18-24": 28.5,
      "25-34": 45.2,
      "35-44": 18.3,
      "45+": 8.0
    },
    "gender": {
      "male": 68.5,
      "female": 31.5
    }
  },
  "insights": [
    {
      "type": "trend",
      "message": "Tutorial content is performing 45% better than average",
      "priority": "high",
      "data": { "performanceIncrease": 45 }
    },
    {
      "type": "recommendation",
      "message": "Optimal posting time is 2 PM UTC based on audience activity",
      "priority": "medium",
      "data": { "recommendedTime": "14:00 UTC" }
    },
    {
      "type": "alert",
      "message": "Average view duration decreased by 8% - consider shorter intros",
      "priority": "high",
      "data": { "change": -8 }
    }
  ],
  "timestamp": "2026-03-05T10:30:45.123Z"
}

Error

{
  "error": "Failed to fetch YouTube Analytics API data: Invalid credentials"
}

Response Codes

Status Code	Description
200	Analytics retrieved successfully
500	Server error retrieving analytics

Use Cases

Performance Dashboard

Build a real-time analytics dashboard:

async function updateDashboard() {
  const response = await fetch('http://localhost:3456/analytics');
  const analytics = await response.json();
  
  document.getElementById('total-views').textContent = 
    analytics.overview.totalViews.toLocaleString();
  
  document.getElementById('subscribers').textContent = 
    '+' + analytics.overview.subscribersGained;
  
  // Display insights
  const insightsList = document.getElementById('insights');
  analytics.insights.forEach(insight => {
    const li = document.createElement('li');
    li.textContent = insight.message;
    li.className = insight.priority;
    insightsList.appendChild(li);
  });
}

// Update every 5 minutes
setInterval(updateDashboard, 5 * 60 * 1000);

Automated Reporting

Generate weekly performance reports:

import requests
from datetime import datetime

def generate_weekly_report():
    response = requests.get('http://localhost:3456/analytics')
    analytics = response.json()
    
    report = f"""
    Weekly Performance Report
    Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}
    
    Overview:
    - Total Views: {analytics['overview']['totalViews']:,}
    - Subscribers Gained: {analytics['overview']['subscribersGained']:,}
    - Engagement Rate: {analytics['overview']['engagementRate']}%
    
    Top Performing Video:
    {analytics['topVideos'][0]['title']}
    ({analytics['topVideos'][0]['views']:,} views)
    
    Key Insights:
    """
    
    for insight in analytics['insights']:
        if insight['priority'] == 'high':
            report += f"\n⚠️  {insight['message']}"
    
    return report

print(generate_weekly_report())

Content Strategy Optimization

Use analytics to inform content decisions:

async function analyzeContentStrategy() {
  const response = await fetch('http://localhost:3456/analytics');
  const analytics = await response.json();
  
  // Find best performing content types
  const topVideos = analytics.topVideos;
  const avgEngagement = topVideos.reduce((sum, v) => sum + v.engagement, 0) / topVideos.length;
  
  console.log('High-performing videos:');
  topVideos
    .filter(v => v.engagement > avgEngagement)
    .forEach(v => console.log(`- ${v.title} (${v.engagement}% engagement)`));
  
  // Check insights for recommendations
  const recommendations = analytics.insights
    .filter(i => i.type === 'recommendation');
  
  console.log('\nRecommendations:');
  recommendations.forEach(r => console.log(`- ${r.message}`));
}

Analytics data is fetched from the YouTube Analytics API. The agent caches data to avoid hitting API rate limits. Data may be up to 15 minutes old.

Data Freshness

The Analytics & Optimization Agent updates data on the following schedule:

Real-time metrics: Updated every 15 minutes
Detailed analytics: Updated every 6 hours
Demographic data: Updated daily
AI insights: Regenerated every 12 hours

Privacy and Compliance

All analytics data is:

Aggregated and anonymized per YouTube’s terms
Stored securely in the local database
Never shared with third parties
Compliant with YouTube’s API Terms of Service

⌘I

REST API

Agents

Endpoint

Description

Request

Headers

Response

Example Request

Example Response

Success

Error

Response Codes

Use Cases

Performance Dashboard

Automated Reporting

Content Strategy Optimization

Data Freshness

Privacy and Compliance

​Endpoint

​Description

​Request

​Headers

​Response

​Example Request

​Example Response

​Success

​Error

​Response Codes

​Use Cases

​Performance Dashboard

​Automated Reporting

​Content Strategy Optimization

​Data Freshness

​Privacy and Compliance

Endpoint

Description

Request

Headers

Response

Example Request

Example Response

Success

Error

Response Codes

Use Cases

Performance Dashboard

Automated Reporting

Content Strategy Optimization

Data Freshness

Privacy and Compliance