{"skill":{"slug":"youtube-reporting","displayName":"YouTube Reporting","summary":"YouTube Reporting API integration with managed OAuth. Schedule and download bulk YouTube Analytics reports as CSV files. Use this skill when users want to sc...","description":"---\nname: youtube-reporting\ndescription: |\n  YouTube Reporting API integration with managed OAuth. Schedule and download bulk YouTube Analytics reports as CSV files.\n  Use this skill when users want to schedule bulk reporting jobs, list available report types, download daily generated reports, or manage reporting jobs for their YouTube channel.\n  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).\n  Requires network access and valid Maton API key.\nmetadata:\n  author: maton\n  version: \"1.0\"\n  clawdbot:\n    emoji: 🧠\n    homepage: \"https://maton.ai\"\n    requires:\n      env:\n        - MATON_API_KEY\n---\n\n# YouTube Reporting\n\nAccess the YouTube Reporting API with managed OAuth authentication. Schedule bulk reporting jobs that generate daily downloadable CSV reports containing channel or playlist analytics data.\n\n## Quick Start\n\n```bash\n# List available report types\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/reportTypes')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n## Base URL\n\n```\nhttps://api.maton.ai/youtube-reporting/{native-api-path}\n```\n\nMaton proxies requests to `youtubereporting.googleapis.com` and automatically injects your OAuth token.\n\n## Authentication\n\nAll requests require the Maton API key in the Authorization header:\n\n```\nAuthorization: Bearer $MATON_API_KEY\n```\n\n**Environment Variable:** Set your API key as `MATON_API_KEY`:\n\n```bash\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n```\n\n### Getting Your API Key\n\n1. Sign in or create an account at [maton.ai](https://maton.ai)\n2. Go to [maton.ai/settings](https://maton.ai/settings)\n3. Copy your API key\n\n## Connection Management\n\nManage your YouTube Reporting OAuth connections at `https://api.maton.ai`.\n\n### List Connections\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections?app=youtube-reporting&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Create Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'youtube-reporting'}).encode()\nreq = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Get Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"connection\": {\n    \"connection_id\": \"{connection_id}\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"youtube-reporting\",\n    \"metadata\": {}\n  }\n}\n```\n\nOpen the returned `url` in a browser to complete OAuth authorization.\n\n### Delete Connection\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Specifying Connection\n\nIf you have multiple YouTube Reporting connections, specify which one to use with the `Maton-Connection` header:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/reportTypes')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Maton-Connection', '{connection_id}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\nIf you have multiple connections, always include this header to ensure requests go to the intended account.\n\n## Security & Permissions\n\n- Access is scoped to the YouTube channel(s) associated with the connected Google account.\n- Report data is read-only (downloaded CSV files).\n- **Job creation and deletion require explicit user approval.** Before creating or deleting a reporting job, confirm the report type and intended effect with the user.\n\n## API Reference\n\n### Report Types\n\n#### List Report Types\n\n```bash\nGET /youtube-reporting/v1/reportTypes\n```\n\n**Optional Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `pageSize` | number | Number of results per page |\n| `pageToken` | string | Token for retrieving next page |\n| `includeSystemManaged` | boolean | Include system-managed report types (default: `false`) |\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/reportTypes')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"reportTypes\": [\n    {\n      \"id\": \"channel_basic_a3\",\n      \"name\": \"User activity\"\n    },\n    {\n      \"id\": \"channel_demographics_a1\",\n      \"name\": \"Demographics\"\n    },\n    {\n      \"id\": \"channel_device_os_a3\",\n      \"name\": \"Device and OS\"\n    },\n    {\n      \"id\": \"channel_traffic_source_a3\",\n      \"name\": \"Traffic sources\"\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n```\n\n**Available Channel Report Types:**\n\n| Report Type ID | Name |\n|----------------|------|\n| `channel_basic_a3` | User activity |\n| `channel_combined_a3` | Combined |\n| `channel_demographics_a1` | Demographics |\n| `channel_device_os_a3` | Device and OS |\n| `channel_annotations_a1` | Annotations |\n| `channel_cards_a1` | Cards |\n| `channel_end_screens_a1` | End screens |\n| `channel_playback_location_a3` | Playback locations |\n| `channel_province_a3` | Province |\n| `channel_reach_basic_a1` | Reach basic |\n| `channel_reach_combined_a1` | Reach combined |\n| `channel_sharing_service_a1` | Sharing service |\n| `channel_subtitles_a3` | Subtitles |\n| `channel_traffic_source_a3` | Traffic sources |\n\n**Available Playlist Report Types:**\n\n| Report Type ID | Name |\n|----------------|------|\n| `playlist_basic_a2` | Playlist user activity |\n| `playlist_combined_a2` | Playlist combined |\n| `playlist_device_os_a2` | Playlist device and OS |\n| `playlist_playback_location_a2` | Playlist playback locations |\n| `playlist_province_a2` | Playlist province |\n| `playlist_traffic_source_a2` | Playlist traffic sources |\n\n### Jobs\n\n#### List Jobs\n\n```bash\nGET /youtube-reporting/v1/jobs\n```\n\n**Optional Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `pageSize` | number | Number of results per page |\n| `pageToken` | string | Token for retrieving next page |\n| `includeSystemManaged` | boolean | Include system-managed jobs (default: `false`) |\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"jobs\": [\n    {\n      \"id\": \"92f0f65f-18c4-4d15-a815-82223ae93ead\",\n      \"reportTypeId\": \"channel_basic_a3\",\n      \"name\": \"Test User Activity Report\",\n      \"createTime\": \"2026-05-04T22:21:48Z\"\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n```\n\n#### Get Job\n\n```bash\nGET /youtube-reporting/v1/jobs/{jobId}\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"id\": \"92f0f65f-18c4-4d15-a815-82223ae93ead\",\n  \"reportTypeId\": \"channel_basic_a3\",\n  \"name\": \"Test User Activity Report\",\n  \"createTime\": \"2026-05-04T22:21:48Z\"\n}\n```\n\n#### Create Job\n\n```bash\nPOST /youtube-reporting/v1/jobs\nContent-Type: application/json\n\n{\n  \"reportTypeId\": \"channel_basic_a3\",\n  \"name\": \"My Daily User Activity Report\"\n}\n```\n\n**Request Body:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `reportTypeId` | string | Yes | Report type ID from `reportTypes.list` |\n| `name` | string | Yes | Display name for the job |\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({\n    \"reportTypeId\": \"channel_basic_a3\",\n    \"name\": \"Daily User Activity\"\n}).encode()\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"id\": \"92f0f65f-18c4-4d15-a815-82223ae93ead\",\n  \"reportTypeId\": \"channel_basic_a3\",\n  \"name\": \"Daily User Activity\",\n  \"createTime\": \"2026-05-04T22:21:48.331114Z\"\n}\n```\n\n#### Delete Job\n\n```bash\nDELETE /youtube-reporting/v1/jobs/{jobId}\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nresp = urllib.request.urlopen(req)\nprint(f\"Status: {resp.status}\")\nEOF\n```\n\nReturns empty response on success.\n\n### Reports\n\n#### List Reports for a Job\n\n```bash\nGET /youtube-reporting/v1/jobs/{jobId}/reports\n```\n\n**Optional Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `createdAfter` | string | Filter reports created after this timestamp (RFC3339 UTC) |\n| `startTimeAtOrAfter` | string | Filter by report data start time (on or after) |\n| `startTimeBefore` | string | Filter by report data start time (before) |\n| `pageSize` | number | Number of results per page |\n| `pageToken` | string | Token for retrieving next page |\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}/reports')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"reports\": [\n    {\n      \"id\": \"report-id-123\",\n      \"startTime\": \"2025-04-01T07:00:00Z\",\n      \"endTime\": \"2025-04-02T07:00:00Z\",\n      \"downloadUrl\": \"https://youtubereporting.googleapis.com/...\",\n      \"createTime\": \"2025-04-02T10:00:00Z\"\n    }\n  ],\n  \"nextPageToken\": \"...\"\n}\n```\n\n#### Get Report\n\n```bash\nGET /youtube-reporting/v1/jobs/{jobId}/reports/{reportId}\n```\n\n**Example:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/youtube-reporting/v1/jobs/{job_id}/reports/{report_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n#### Download Report\n\nReports provide a `downloadUrl` that returns a CSV file. Download via an authorized GET request:\n\n```bash\npython <<'EOF'\nimport urllib.request, os\nreq = urllib.request.Request('{download_url}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nwith urllib.request.urlopen(req) as resp:\n    data = resp.read().decode('utf-8')\n    print(data[:2000])\nEOF\n```\n\n## Pagination\n\nAll list endpoints use token-based pagination:\n\n```bash\nGET /youtube-reporting/v1/reportTypes?pageSize=5&pageToken={nextPageToken}\n```\n\nResponse includes `nextPageToken` when more results exist:\n\n```json\n{\n  \"reportTypes\": [...],\n  \"nextPageToken\": \"channel_device_os_a3\"\n}\n```\n\nPass the `nextPageToken` value as `pageToken` in the next request to retrieve subsequent pages.\n\n## Code Examples\n\n### JavaScript\n\n```javascript\nconst response = await fetch(\n  'https://api.maton.ai/youtube-reporting/v1/jobs',\n  {\n    headers: {\n      'Authorization': `Bearer ${process.env.MATON_API_KEY}`\n    }\n  }\n);\nconst data = await response.json();\nconsole.log(data.jobs);\n```\n\n### Python\n\n```python\nimport os\nimport requests\n\n# List all jobs\nresponse = requests.get(\n    'https://api.maton.ai/youtube-reporting/v1/jobs',\n    headers={'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}'}\n)\njobs = response.json().get('jobs', [])\n\n# List reports for first job\nif jobs:\n    reports_resp = requests.get(\n        f'https://api.maton.ai/youtube-reporting/v1/jobs/{jobs[0][\"id\"]}/reports',\n        headers={'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}'}\n    )\n    print(reports_resp.json())\n```\n\n## Notes\n\n- Reports are generated daily; the first report is available within 24 hours of job creation\n- Report data covers a single day (startTime to endTime spans 24 hours)\n- Downloaded reports are CSV files with headers in the first row\n- A job with a given `reportTypeId` can only exist once; creating a duplicate returns 409 Conflict\n- System-managed jobs are auto-generated by YouTube and cannot be created or deleted (403 Forbidden)\n- After deleting a job, previously generated reports remain downloadable for up to 60 days\n- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing\n- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Bad request (missing name or reportTypeId, invalid reportTypeId, deprecated report type) |\n| 401 | Invalid or missing Maton API key |\n| 403 | Forbidden (cannot create/delete system-managed jobs) |\n| 404 | Job or report not found |\n| 409 | Conflict (job with same reportTypeId already exists) |\n| 429 | Rate limited |\n| 4xx/5xx | Passthrough error from YouTube Reporting API |\n\n### Troubleshooting: API Key Issues\n\n1. Check that the `MATON_API_KEY` environment variable is set:\n\n```bash\necho $MATON_API_KEY\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Troubleshooting: Invalid App Name\n\n1. Ensure your URL path starts with `youtube-reporting`. For example:\n\n- Correct: `https://api.maton.ai/youtube-reporting/v1/jobs`\n- Incorrect: `https://api.maton.ai/v1/jobs`\n\n## Resources\n\n- [YouTube Reporting API Overview](https://developers.google.com/youtube/reporting)\n- [YouTube Reporting API Reference](https://developers.google.com/youtube/reporting/v1/reference/rest)\n- [Bulk Reports](https://developers.google.com/youtube/reporting/v1/reports)\n- [Report Types](https://developers.google.com/youtube/reporting/v1/report_types)\n- [Maton Community](https://discord.com/invite/dBfFAcefs2)\n- [Maton Support](mailto:support@maton.ai)\n","topics":["CSV","Api Integration","Schedule"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":374,"installsAllTime":14,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778148818251,"updatedAt":1781739751880},"latestVersion":{"version":"1.0.0","createdAt":1778148818251,"changelog":"Initial release of YouTube Reporting API integration with managed OAuth.\n\n- Schedule and manage bulk YouTube Analytics reporting jobs via a unified API.\n- Download daily-generated YouTube Analytics reports as CSV files.\n- List available report types for both channels and playlists.\n- Manage multiple YouTube account connections with easy OAuth management.\n- Secure API access with Maton API key authentication.","license":"MIT-0"},"metadata":{"setup":[{"key":"MATON_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"byungkyu","userId":"s174c3s2kc1ehqj1ytzntezj2983e2aj","displayName":"byungkyu","image":"https://avatars.githubusercontent.com/u/16563684?v=4"},"moderation":null}