YouTube Reporting

Access the YouTube Reporting API with managed OAuth authentication. Schedule bulk reporting jobs that generate daily downloadable CSV reports containing channel or playlist analytics data.

Reference

List Report Types

GET /youtube-reporting/v1/reportTypes

Optional Parameters:

Parameter	Type	Description
`pageSize`	number	Number of results per page
`pageToken`	string	Token for retrieving next page
`includeSystemManaged`	boolean	Include system-managed report types (default: `false`)

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/reportTypes')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "reportTypes": [
    {
      "id": "channel_basic_a3",
      "name": "User activity"
    },
    {
      "id": "channel_demographics_a1",
      "name": "Demographics"
    },
    {
      "id": "channel_device_os_a3",
      "name": "Device and OS"
    },
    {
      "id": "channel_traffic_source_a3",
      "name": "Traffic sources"
    }
  ],
  "nextPageToken": "..."
}

Available Channel Report Types:

Report Type ID	Name
`channel_basic_a3`	User activity
`channel_combined_a3`	Combined
`channel_demographics_a1`	Demographics
`channel_device_os_a3`	Device and OS
`channel_annotations_a1`	Annotations
`channel_cards_a1`	Cards
`channel_end_screens_a1`	End screens
`channel_playback_location_a3`	Playback locations
`channel_province_a3`	Province
`channel_reach_basic_a1`	Reach basic
`channel_reach_combined_a1`	Reach combined
`channel_sharing_service_a1`	Sharing service
`channel_subtitles_a3`	Subtitles
`channel_traffic_source_a3`	Traffic sources

Available Playlist Report Types:

Report Type ID	Name
`playlist_basic_a2`	Playlist user activity
`playlist_combined_a2`	Playlist combined
`playlist_device_os_a2`	Playlist device and OS
`playlist_playback_location_a2`	Playlist playback locations
`playlist_province_a2`	Playlist province
`playlist_traffic_source_a2`	Playlist traffic sources

List Jobs

GET /youtube-reporting/v1/jobs

Optional Parameters:

Parameter	Type	Description
`pageSize`	number	Number of results per page
`pageToken`	string	Token for retrieving next page
`includeSystemManaged`	boolean	Include system-managed jobs (default: `false`)

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "jobs": [
    {
      "id": "92f0f65f-18c4-4d15-a815-82223ae93ead",
      "reportTypeId": "channel_basic_a3",
      "name": "Test User Activity Report",
      "createTime": "2026-05-04T22:21:48Z"
    }
  ],
  "nextPageToken": "..."
}

Get Job

GET /youtube-reporting/v1/jobs/{jobId}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "id": "92f0f65f-18c4-4d15-a815-82223ae93ead",
  "reportTypeId": "channel_basic_a3",
  "name": "Test User Activity Report",
  "createTime": "2026-05-04T22:21:48Z"
}

Create Job

POST /youtube-reporting/v1/jobs
Content-Type: application/json

{
  "reportTypeId": "channel_basic_a3",
  "name": "My Daily User Activity Report"
}

Request Body:

Field	Type	Required	Description
`reportTypeId`	string	Yes	Report type ID from `reportTypes.list`
`name`	string	Yes	Display name for the job

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "reportTypeId": "channel_basic_a3",
    "name": "Daily User Activity"
}).encode()
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "id": "92f0f65f-18c4-4d15-a815-82223ae93ead",
  "reportTypeId": "channel_basic_a3",
  "name": "Daily User Activity",
  "createTime": "2026-05-04T22:21:48.331114Z"
}

Delete Job

DELETE /youtube-reporting/v1/jobs/{jobId}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
resp = urllib.request.urlopen(req)
print(f"Status: {resp.status}")
EOF

Returns empty response on success.

List Reports for a Job

GET /youtube-reporting/v1/jobs/{jobId}/reports

Optional Parameters:

Parameter	Type	Description
`createdAfter`	string	Filter reports created after this timestamp (RFC3339 UTC)
`startTimeAtOrAfter`	string	Filter by report data start time (on or after)
`startTimeBefore`	string	Filter by report data start time (before)
`pageSize`	number	Number of results per page
`pageToken`	string	Token for retrieving next page

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}/reports')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "reports": [
    {
      "id": "report-id-123",
      "startTime": "2025-04-01T07:00:00Z",
      "endTime": "2025-04-02T07:00:00Z",
      "downloadUrl": "https://youtubereporting.googleapis.com/...",
      "createTime": "2025-04-02T10:00:00Z"
    }
  ],
  "nextPageToken": "..."
}

Get Report

GET /youtube-reporting/v1/jobs/{jobId}/reports/{reportId}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}/reports/{report_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Download Report

Reports provide a downloadUrl that returns a CSV file. Download via an authorized GET request:

python <<'EOF'
import urllib.request, os
req = urllib.request.Request('{download_url}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
with urllib.request.urlopen(req) as resp:
    data = resp.read().decode('utf-8')
    print(data[:2000])
EOF

YouTube Reporting

Reference

List Report Types

List Jobs

Get Job

Create Job

Delete Job

List Reports for a Job

Get Report

Download Report

Resources

On this page