1. Docs
  2. Investigate
  3. Share Query

Share a Query

Create shareable links that automatically run queries.

Query template links let you share queries with your team or link to queries from external tools like runbooks, dashboards, or incident response systems. These links are especially helpful when connecting Honeycomb to third-party tools or documenting common investigations, so you can jump straight from documentation or alerts to relevant query results.

A query template link is a Honeycomb URL with a query parameter that defines a query specification. When someone opens a query template link, Honeycomb automatically runs the query and displays the results.

Note
Embedding Honeycomb pages, including query results, within an iframe isn’t supported.

The easiest way to create a query template link to build your query in Honeycomb and copy the generated link.

To get a query template link:

  1. Select Query (Query menu icon) from the navigation menu.

  2. Build your query in Query Builder, and select Run Query.

  3. Select Share (Share icon).

  4. In the modal, select Get Template Link

    Share menu with open modal containing 'Get Template Link'.

  5. Select Copy link to copy the URL.

    Modal showing Query Template URL and 'Copy link'

Your query template link is copied to your clipboard and ready to share.

Construct query template links programmatically by combining a Dataset URL with a JSON query parameter. This is useful for generating links from scripts, automation tools, or third-party systems.

URL Format 

To create a query template link, construct a URL in this format:

https://ui.honeycomb.io/<team>/environments/<environment>/datasets/<dataset>/?query=<query_json>

When opened, Honeycomb runs the query specified in the query parameter and displays the results.

URL Parameters 

Each part of the URL identifies where to run the query and what query to execute:

Dataset Context Parameters 

  • team: Slug for the Team in Honeycomb. This short, URL-friendly string uniquely identifies your Team and appears in Honeycomb URLs.
  • environment: Slug for the Environment in Honeycomb. This short, URL-friendly string uniquely identifies your Environment and appears in Honeycomb URLs.
  • dataset: Slug for the Dataset in Honeycomb. This short, URL-friendly string uniquely identifies your Dataset and appears in Honeycomb URLs.

Query Parameters 

  • query: JSON string that defines the query specification. The query parameter value can include calculations, filters, breakdowns, time ranges, and visualization settings. For complete specification details, visit Define a Query via JSON.

Examples 

This example shows a complete query template link that runs a basic COUNT query with a filter of duration_ms > 500:

https://ui.honeycomb.io/my-team/environments/production/datasets/frontend/?query={"calculations":[{"op":"COUNT"}],"filters":[{"column":"duration_ms","op":">","value":500}]}

This example shows a more complex query with P95 calculation and breakdown by HTTP route:

https://ui.honeycomb.io/my-team/environments/production/datasets/frontend/?query={"calculations":[{"op":"P95","column":"duration_ms"}],"breakdowns":["http.route"]}

Best Practices 

Follow these tips to build useful query template links:

  • Test your links: Always open query template links in a browser to verify they work as expected before sharing them.
  • Use descriptive context: When sharing links in documentation or runbooks, add context about what the query shows (for example, “Check API error rates over the last hour”).
  • Keep queries focused: Simpler queries are easier to understand and maintain. Consider multiple focused links instead of one complex query.
  • URL-encode when necessary: If your query JSON contains special characters, ensure proper URL encoding to prevent broken links.
  • Document your links: If you are embedding query template links in tools or documentation, add comments explaining what each query investigates.
  • Version control your links: Store frequently-used query template links in version-controlled runbooks or documentation so your team can track changes over time.

Limitations 

Keep these points in mind to ensure your query template links work as expected:

  • Embedding isn’t supported: Honeycomb pages, including query results, cannot be displayed within an iframe.
  • Field availability varies by Dataset: Queries reference specific fields that must exist in the target Dataset. Links may fail if the Dataset doesn’t contain the referenced fields.
  • JSON formatting matters: The query parameter must be valid JSON. Syntax errors will prevent the query from running.
  • Browser URL length limits: Extremely complex queries may exceed browser URL length limits (typically around 2000 characters). Consider simplifying the query or using the UI to generate the link.
On this page: