Skip to main content

​
Overview

Connect your YouTube channel to Ana to analyze video performance, track engagement metrics, and gain insights into your content strategy. Ana can fetch video statistics, subscriber counts, and engagement data directly from the YouTube Data API v3. Quick Summary: Set up OAuth 2.0 credentials in Google Cloud Platform, authorize Ana to access your YouTube channel, and store the credentials in TextQL’s Secrets Manager.

​
Prerequisites

GitHub Context Management Recommended: This integration works best with GitHub-based context management. While other context managers (like Notion) may work, the documentation and setup instructions assume GitHub is configured. See the Persistent Memory guide for setup instructions.
You’ll need:
  • A Google account with access to your YouTube channel
  • Admin access to Google Cloud Platform (or ability to create a GCP project)
  • Access to TextQL’s Secrets Manager (organization admin)

​
How It Works

Once configured, Ana can:
  1. Fetch video statistics (views, likes, comments, engagement)
  2. Analyze channel growth and subscriber trends
  3. Track video performance over time
  4. Search and filter videos by topic or date
  5. Generate reports on content performance
The integration uses OAuth 2.0 authentication with read-only access to your YouTube data.

​
Setup Instructions

​
1. Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Click “Select a project” at the top
  3. Click “New Project”
  4. Enter a project name (e.g., “youtube-analytics”)
  5. Click “Create”

​
2. Enable YouTube Data API v3

  1. In your new project, go to “APIs & Services” → “Library”
  2. Search for “YouTube Data API v3”
  3. Click on it and click “Enable”
  4. Wait a few seconds for the API to be enabled
  1. Go to “APIs & Services” → “OAuth consent screen”
  2. Choose “External” user type (unless you have Google Workspace)
  3. Click “Create”
  4. Fill in required fields:
    • App name: Your app name (e.g., “YouTube Analytics”)
    • User support email: Your email
    • Developer contact email: Your email
  5. Click “Save and Continue”
  6. Skip “Scopes” (click “Save and Continue”)
  7. Add Test Users:
    • Click “Add Users”
    • Enter your Google/YouTube account email
    • Click “Add”
    • Click “Save and Continue”
  8. Review and click “Back to Dashboard”
Important: You must add yourself as a test user in step 7, or you’ll get an “Access blocked” error during authorization.

​
4. Create OAuth 2.0 Client ID

  1. Go to “APIs & Services” → “Credentials”
  2. Click “Create Credentials” → “OAuth 2.0 Client ID”
  3. Choose application type: “Desktop app”
  4. Give it a name (e.g., “YouTube Data Access”)
  5. Click “Create”
  6. Download the JSON file:
    • Click the download button (down arrow icon)
    • Save the file (it will be named something like client_secret_xxx.json)
The downloaded file will have this structure: 
{
  "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "client_secret": "YOUR_CLIENT_SECRET"
}

​
5. Generate Authorization URL

Ask Ana to generate an authorization URL using your client credentials: 
I need to connect my YouTube channel to Ana. I have the OAuth client credentials JSON file. 
Can you generate an authorization URL for me?
Upload the downloaded JSON file to Ana, and she will generate a URL that looks like: 
https://accounts.google.com/o/oauth2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly...

​
6. Authorize Your YouTube Account

  1. Copy and paste the authorization URL into your browser
  2. Log in with your Google account (the one with your YouTube channel)
  3. Select your YouTube channel if prompted
  4. Grant permissions when asked (read-only access to YouTube data)
  5. You’ll be redirected to a URL that starts with http://localhost/?code=...
    • The page won’t load (that’s normal - localhost isn’t running)
    • Copy the ENTIRE URL from your browser’s address bar
The redirect URL will look like: 
http://localhost/?code=AUTHORIZATION_CODE&scope=https://www.googleapis.com/auth/youtube.readonly

​
7. Exchange Code for Tokens

Give the redirect URL to Ana: 
Here's the redirect URL from the authorization: [paste the full URL]
Ana will:
  1. Extract the authorization code
  2. Exchange it for an access_token and refresh_token
  3. Fetch your channel information to verify the connection
  4. Generate a complete credentials JSON object

​
8. Store Credentials in Secrets Manager

Ana will provide you with a complete JSON object like this: 
{
  "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "client_secret": "YOUR_CLIENT_SECRET",
  "access_token": "ya29.a0AUMWg_...",
  "refresh_token": "1//06jx6MfHOiA9E...",
  "token_uri": "https://oauth2.googleapis.com/token",
  "channel_id": "UCxxxxxxxxxxxxxxxxxx",
  "channel_title": "Your Channel Name"
}
To add it to TextQL:
  1. Go to Settings → Secrets in TextQL
  2. Click “Add Secret”
  3. Name: YOUTUBE_TOKEN (or your preferred name)
  4. Value: Paste the entire JSON object
  5. Click “Save”

​
9. Update Context Documentation

Ana uses context to understand how to interact with your APIs and data sources. This step documents the YouTube integration in your context repository so Ana knows how to use it in future sessions.
GitHub Context Management: These instructions are written for GitHub-based context management. If you’re using a different context manager (Notion, native context library, etc.), the process for documenting integrations should be intuitive for active users. For questions, contact [email protected].For GitHub setup instructions, see the Persistent Memory guide.
Ask Ana to update your context documentation: 
I've added the YouTube credentials to Secrets as YOUTUBE_TOKEN.
Can you update the context repository to document this integration?
Ana will:
  1. Create API documentation in your context repository
  2. Update the context overview with YouTube routing information
  3. Submit a pull request for your review
Always review pull requests before merging. Verify that the documentation accurately reflects your setup and doesn’t contain sensitive information.

​
Usage Examples

Once configured, you can ask Ana:
  • “Show me my YouTube video performance from the last month”
  • “What are my top 10 most viewed videos?”
  • “Analyze subscriber growth over time”
  • “Which videos have the best engagement rate?”
  • “Create a report on my YouTube channel metrics”
  • “How many views did my recent videos get?”

​
Troubleshooting

​
Error: “Access blocked: App not verified”

Solution: You forgot to add yourself as a test user in the OAuth consent screen.
  1. Go to “APIs & Services” → “OAuth consent screen”
  2. Scroll to “Test users”
  3. Click “Add Users”
  4. Add your email address
  5. Try authorization again

​
Error: “Invalid grant” or “Token expired”

Solution: The authorization code expired (they only last 10 minutes).
  1. Generate a new authorization URL from Ana
  2. Complete the authorization process again
  3. Give Ana the new redirect URL immediately

​
Error: “YouTube Data API v3 has not been used”

Solution: The API isn’t enabled in your GCP project.
  1. Go to the link provided in the error message
  2. Click “Enable”
  3. Wait a few seconds and try again

​
Can’t see my videos

Solution: Make sure you’re authorizing with the correct Google account that owns the YouTube channel.

​
Security Notes

  • Access tokens expire after 1 hour (Ana handles refresh automatically using the refresh token)
  • Refresh tokens don’t expire (Ana uses them to get new access tokens)
  • Never share your tokens publicly - they provide access to your YouTube data
  • You can revoke access anytime at Google Account Permissions
  • The integration uses read-only access - Ana cannot modify your YouTube channel

​
API Quota

YouTube Data API v3 has a free quota of 10,000 units per day:
  • Reading video data: 1-3 units per request
  • You can pull your video data thousands of times per day
  • Quota resets at midnight Pacific Time
  • No charges - completely free for typical usage
To check your quota usage:
  1. Go to Google Cloud Console
  2. Select your project
  3. Navigate to “APIs & Services” → “Dashboard”
  4. Click “YouTube Data API v3”
  5. View your daily usage

​
Need Help?

For further assistance, please contact [email protected].

​
Privacy Policy

For information about how we handle your data and protect your privacy when using TextQL’s YouTube integration, please review our Privacy Policy.