Skip to main content

Looker

Looker is a business intelligence platform owned by Google Cloud that enables organizations to explore data, create dashboards, and build data-driven applications. With Looker's semantic modeling layer (LookML), organizations can define business logic once and ensure consistent metrics across all analyses. Looker provides powerful data exploration through Explores, saved queries (Looks), interactive dashboards, and scheduled content delivery.

Authentication Types​

Looker supports OAuth authentication:

  • OAuth (PKCE) - Register a Looker OAuth client application on your instance, then each user connects with their own Looker account. Looker issues short-term access tokens (with refresh tokens) via the Authorization Code flow with PKCE — no client secret is required.
    • Pros: Secure, per-user permissions and audit trails, refresh tokens, no shared secret to store
    • Cons: Requires a one-time OAuth app registration by a Looker admin
    • Best for: All Looker API integrations where per-user identity and permissions matter

Configuration​

Before using the connector, you need to configure:

  • Looker Instance URL - Your full Looker instance URL including protocol and port if non-standard
    • Format: https://<instance_name>.cloud.looker.com (most modern instances)
    • Legacy format: https://<instance_name>.cloud.looker.com:19999 (older AWS instances)
tip

You can find your instance URL in your browser's address bar when logged into Looker. For example:

  • URL: https://mycompany.cloud.looker.com → Instance URL: https://mycompany.cloud.looker.com
  • URL: https://analytics.cloud.looker.com:19999 → Instance URL: https://analytics.cloud.looker.com:19999

Include the full URL with https:// and the port number if it's not the standard 443.

Setting up OAuth​

Looker requires every OAuth client application to be registered with your instance before users can authenticate. This is a one-time setup performed by a Looker admin using the register_oauth_client_app API endpoint.

Step 1: Copy the redirect URL​

  1. In Willow, go to Integrations → New → Built-in and select Looker

  2. Choose OAuth as the authentication method

  3. Copy the callback URL shown in the setup wizard — you'll need it as the redirect_uri in the next step

Step 2: Register the OAuth client application​

  1. Open the API Explorer on your Looker instance:

    • Development → API Explorer, or navigate to https://<your-instance>/extensions/marketplace_extension_api_explorer::api-explorer

  2. Using the version drop-down, choose the 4.0 - stable API version

  3. Find the register_oauth_client_app endpoint (search for oauth app)

  4. Click Run It, provide the following parameters, and click Run It again:

    • client_guid: A globally unique ID you choose for the app (e.g. willow). This becomes your Client ID.
    • redirect_uri: The callback URL you copied in Step 1. It must match exactly, or authentication will be denied.
    • display_name: A name shown to users, e.g. Willow
    • description: A short description shown on the consent screen, e.g. Willow MCP integration
tip

You can also register the app programmatically by calling register_oauth_client_app with an admin API token instead of using the API Explorer.

warning

The client_guid and redirect_uri you register must match the values Willow presents exactly. If either differs, Looker treats the login request as a forgery and rejects it.

Step 3: Connect in Willow​

  1. Back in the Willow setup wizard, enter the client_guid you chose as the Client ID

    tip

    No Client Secret is needed — Looker uses PKCE (Proof Key for Code Exchange) for public clients. The Client ID combined with PKCE is sufficient for secure authentication.

  2. Enter your Looker Instance URL in the Configuration section

    • Example: https://mycompany.cloud.looker.com
    • Include the port if your instance serves the API on a non-standard port, e.g. https://mycompany.cloud.looker.com:19999

  3. Click Save / Connect, then complete the Looker login and consent prompt in the popup

  4. On success, Willow stores the access and refresh tokens and establishes the connection

Best Practices​

Per-User Permissions​

With OAuth, API requests execute with the permissions of the connected user — each person who authorizes the integration acts under their own Looker identity. Ensure users have:

  • See and Explore permissions for models and explores you want to query
  • View access to folders containing dashboards and Looks you want to access
  • Create and Edit permissions if the integration needs to create or modify content
  • Appropriate Role assignments (Admin, Developer, User, Viewer) based on your use case

OAuth App Management​

  • Register a single, clearly named OAuth client app (e.g. willow) so it's easy to identify in audit logs
  • A Looker admin can revoke all tokens for the app at any time by disabling it or setting tokens_invalid_before via update_oauth_client_app
  • Refresh tokens have a one-month lifetime; users are transparently re-prompted to log in when a refresh token expires

Security​

  • Use HTTPS for all API communications (enforced by Looker)
  • Monitor API usage through Looker's system activity logs
  • Disable the OAuth app immediately if you suspect its client_guid has been misused

Common Use Cases​

Automated Reporting​

Use scheduled plans to deliver dashboard or Look data automatically:

1. Use "List Dashboards" or "Search Dashboards" to find the dashboard
2. Use "Create Scheduled Plan" with a cron expression to set up delivery
3. Specify email addresses and format (PDF, CSV, Excel, etc.)

Data Extraction​

Extract data from Looker for external processing:

1. Use "List LookML Models" to discover available data models
2. Use "Get Explore Metadata" to understand available fields
3. Use "Create Query" to build a custom query
4. Use "Run Query" with format "csv" or "json_bi" to get results

Content Management​

Organize and maintain your Looker content:

1. Use "List Folders" to understand your folder structure
2. Use "Create Folder" to create new organizational structures
3. Use "Update Dashboard" or "Update Look" to move content into folders
4. Use "Search Content" to find content needing organization

Dashboard Discovery​

Help users find relevant dashboards:

1. Use "Search Dashboards" with keywords from user questions
2. Use "Get Dashboard" to retrieve dashboard details
3. Use "Get Folder" to find related content in the same folder
4. Use "List Favorite Content" to surface frequently used dashboards

Troubleshooting​

Error: "401 Unauthorized" or "Authentication Failed"​

Cause: The access token is invalid/expired, or the OAuth app registration doesn't match.

Solution:

  1. Reconnect the integration to trigger a fresh Looker login (refresh tokens expire after one month)
  2. Verify the Client ID you entered matches the client_guid you registered with register_oauth_client_app
  3. Confirm the registered redirect_uri matches Willow's callback URL exactly
  4. Check that the OAuth app is enabled (not disabled) and that tokens_invalid_before hasn't invalidated existing tokens
  5. Ensure the connecting user account still exists and is active in Looker

Error: "Forgery" or login request rejected​

Cause: The client_guid or redirect_uri in the login request doesn't match the registered OAuth app.

Solution:

  1. Re-run register_oauth_client_app (or update_oauth_client_app) so the redirect_uri exactly matches the callback URL shown in Willow
  2. Make sure the Client ID entered in Willow is identical to the registered client_guid

Error: "404 Not Found" when accessing API​

Cause: Incorrect Instance URL or API path.

Solution:

  1. Verify your Instance URL is correct and includes https://
  2. Check if your instance uses a non-standard port (e.g., :19999)
  3. Ensure the Instance URL does NOT include /api/4.0 (this is added automatically)
  4. Test your Instance URL by visiting it in a browser - you should see the Looker login page

Error: "403 Forbidden" or "Insufficient Permissions"​

Cause: The user account lacks necessary permissions.

Solution:

  1. Verify the user has access to the requested content (dashboard, Look, folder, etc.)
  2. Check the user's Role assignments in Admin → Users
  3. Ensure the user has appropriate Model Set permissions for querying data
  4. For admin operations (user/group management), verify the user has Admin role

Queries Return No Data​

Cause: User permissions or query filters are too restrictive.

Solution:

  1. Verify the user has Explore permissions on the model and explore
  2. Check if user attributes are filtering data (common in row-level security setups)
  3. Test the same query as the user directly in Looker's Explore interface
  4. Review any connection-level permissions or database grants

Scheduled Plans Fail to Create​

Cause: Missing required fields or insufficient permissions.

Solution:

  1. Ensure you specify either dashboard_id OR look_id (not both)
  2. Provide a valid cron expression for the crontab field
  3. Verify the user has permission to schedule content (check Role permissions)
  4. Confirm at least one destination is configured in scheduled_plan_destination
  5. Check that email recipients are valid Looker users (if required by your instance)

Instance URL with Port 19999 Not Working​

Cause: Older AWS instances use port 19999, which may have connectivity restrictions.

Solution:

  1. Verify port 19999 is accessible from your network (not blocked by firewall)
  2. Check with your Looker administrator if the instance has been migrated to port 443
  3. Try both formats: https://instance.cloud.looker.com:19999 and https://instance.cloud.looker.com
  4. Contact Looker support about migrating to the modern port 443 configuration

API Rate Limits​

Looker enforces rate limits on API requests to ensure platform stability:

  • Limits vary by instance and are typically generous for normal usage
  • If you hit rate limits, the API will return HTTP 429 (Too Many Requests)
  • Implement exponential backoff and retry logic for production integrations
  • Consider caching frequently accessed data (model metadata, folder structures, etc.)
  • For high-volume needs, contact your Looker administrator about increasing limits

Additional Resources​

On this page