🎉 Seed RoundWe've raised 2.5M from Swift, YC, & Chapter One. Read more

Learning - 2023-10-12

Analyzing User Behavior with Metal’s List Queries API

by Pablo Rios

Skeletons studying user queries

Skeletons studying user queries

No matter the kind of application you're building, understanding your user’s behaviors is critical.  And while every Metal application comes out of the box with query logs and metrics, sometimes you need to dig deeper and work with more data.

In this post, we'll guide you on how to gain insights from Metal’s list queries API to obtain a clearer picture of user interactions with your application. Armed with these insights, you can improve your index’s data, query relevance, and overall user experience.

Understanding the List Queries API Response

Metal’s list queries API offers a concise snapshot of user queries in real time. For example, let’s consider the following query data from an online bookstore:

"data": [
"t": "2023-10-06T11:06:57.302Z",
"d": 0.154188632965,
"q": "books on astrophysics for beginners"
"t": "2023-10-06T11:05:42.146Z",
"d": 0.196450591087,
"q": "top fantasy novels of 2023"
"t": "2023-10-06T11:05:16.420Z",
"d": 0.18585050106,
"q": "which author wrote the book 'Eternal Nights'?"


  • t: Timestamp of the query
  • d: Cosine distance between the search query and the retrieved embedding. A smaller value indicates a closer match.
  • q: Actual user query

This is how you can call the API via Metal's SDKs.

# Initialize the Metal Client
from metal_sdk.metal import Metal
api_key= 'METAL_API_KEY'
client_id= 'METAL_CLIENT_ID'
metal = Metal(api_key, client_id)
# Get Queries
index_id = '<INDEX_ID>'

Analyzing User Queries

Over time, pulling and analyzing user queries can offer insights into:

  • Popular Search Terms: Identify what users are actively searching for
  • Query Match Quality: By observing the cosine distance, you can determine how closely user queries match the content in the application
  • Potential Gaps in Data: If a query frequently returns a high cosine distance, it might be an indication of data gaps or misalignment in your application or index
  • Temporal Analysis: The timestamps can provide insights into user behavior patterns over time, indicating peak search times or trends

Improving the App 

Depending on the query results, there are several strategies you can follow to enhance your application:

  • Updating the Index Contents: If users are frequently searching for a specific topic or term not present in your index, consider adding it. For instance, if users are querying for "top fantasy novels of 2023" and your application lacks this information, it might be time to update your index.
  • Adding Metadata: Enhance the richness of your content by adding relevant metadata. If a query like "which author wrote the book 'Eternal Nights'?" is common, ensure that author names are part of your index's metadata.
  • Connecting Live Data via a Data Source: If real-time information is crucial, consider integrating live data sources. For instance, for queries like "books on astrophysics for beginners", connecting to a live bookstore's inventory might provide users with real-time availability and prices.

Wrapping up

Analyzing your users' queries is an essential practice for developers and product teams seeking to improve their application's experience. As your application gets more usage over time, leveraging Metal’s APIs is a great way to parse through higher volumes of data. This will let you more easily identify areas of improvement and take actionable steps to provide a superior user experience.

If you would like to try this out today, please get in touch or start a Metal account for yourself here 🎸