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 API Key authentication:

  • API Key - Uses API credentials (client ID and client secret) to generate short-term OAuth 2.0 access tokens.
    • Pros: Secure, per-user permissions, straightforward setup, production-ready
    • Cons: Requires admin access to create credentials, token-based (expires periodically)
    • Best for: All Looker API integrations, automated workflows, embedded analytics applications

General Settings​

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 API Key Authentication​

To use Looker's API, you need to create API credentials that consist of a client ID and client secret. The process differs slightly between Looker (original) and Looker (Google Cloud core).

For Looker (Original) Instances​

  1. Log in to your Looker instance as an administrator

  2. Navigate to Admin → Users in the left sidebar

  3. Find the user account that will own the API credentials (or create a dedicated service account user)

  4. Click Edit on the user account

  5. Scroll down to the API Keys section (may be labeled API3 Keys)

  6. Click Edit Keys or New API Key

  7. Click Generate New API Key or similar button

  8. Copy the Client ID and Client Secret that appear

    warning

    The Client Secret is only shown once! Save it securely immediately. If you lose it, you'll need to generate new credentials.

  9. Click Save to confirm

For Looker (Google Cloud Core) Instances​

Step 1: Enable API Management for User​

  1. Log in to your Looker instance as an administrator

  2. Navigate to Admin → Users in the left sidebar

  3. Find the user account that should have API access

  4. Click Edit on the user account

  5. Locate the API section and check the box to Allow this user to manage their API keys

  6. Click Save

Step 2: Create API Credentials​

  1. Log out of the admin account and log in as the user who was granted API management

  2. Click your profile icon in the top right corner

  3. Select Account from the dropdown menu

  4. Scroll to the API Keys section

  5. Click Edit Keys or New API Key

  6. A dialog will appear with your Client ID and Client Secret

    warning

    The Client Secret is only shown once! Save it securely immediately. If you lose it, you'll need to generate new credentials.

  7. Copy both values and store them securely

  8. Click Done or Save

Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Looker from the list of available connectors

  3. Enter your Looker Instance URL in the General Settings section

    • Example: https://mycompany.cloud.looker.com

  4. In the authentication section, paste:

    • Client ID (from Looker API credentials)
    • Client Secret (from Looker API credentials)

  5. Click Save or Connect

  6. The connector will validate your credentials and establish the connection

Best Practices​

Service Accounts​

For production integrations, create a dedicated service account user in Looker specifically for API access:

  1. Create a new user with an appropriate name (e.g., "API Service Account" or "Webrix Integration")
  2. Grant only the necessary permissions for your integration's use case
  3. Generate API credentials for this service account
  4. Use these credentials instead of personal user accounts

This approach provides:

  • Better security isolation
  • Clearer audit trails
  • Easier credential rotation
  • Permissions that match the integration's needs rather than a human user's needs

Permission Considerations​

API requests execute with the permissions of the user who created the API credentials. Ensure the user has:

  • 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

Security​

  • Never commit API credentials to version control
  • Rotate credentials periodically (e.g., every 90 days)
  • Revoke unused credentials immediately
  • Use HTTPS for all API communications (enforced by Looker)
  • Monitor API usage through Looker's system activity logs

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: Invalid or expired API credentials.

Solution:

  1. Verify your Client ID and Client Secret are correct
  2. Check that the user account still exists and is active in Looker
  3. Ensure the user has not been locked or disabled
  4. Regenerate API credentials if needed (old ones will be invalidated)

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​