Skip to main content
POST
/
v1
/
query
Query the dataset
curl --request POST \
  --url https://platform.datagyro.com/v1/query \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "query_string": "Engineers",
  "dataset_id": "118",
  "limit": 10,
  "use_smaller_model": false
}
'
"data: {\"type\":\"thoughts\",\"data\":{\"filters\":[\"headline contains 'engineer'\"],\"traits\":[\"Profile mentions engineer\"],\"key_phrases\":[\"engineer\",\"engineering\"],\"metadata\":\"SQL construction notes\"},\"created\":1748020550423}\n\n"

​
Core Concepts

​
Datasets

Each dataset in DataGyro has a unique identifier (dataset_id). You’ll need to specify which dataset you want to query in your request.

​
Query Parameters

  • query_string: The search term or phrase you want to find in the dataset
  • dataset_id: The unique identifier for the dataset you want to query
  • limit: Maximum number of results to return (default: 10)
  • use_smaller_model: Option to use a smaller model for faster processing (default: false)

​
Example Request

curl --request POST \
  --url https://platform.datagyro.com/v1/query \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/event-stream' \
  --header 'apikey: YOUR_API_KEY' \
  --data '{
    "query_string": "Engineers",
    "dataset_id": "118",
    "limit": 10,
    "use_smaller_model": false
  }'
Note: The endpoint returns a Server-Sent Events stream, so make sure to include the Accept: text/event-stream header and handle the streaming response appropriately.

​
Response Format

The query endpoint returns a Server-Sent Events (SSE) stream that provides real-time updates during query processing. Each event contains a data field with JSON content.

​
Stream Event Types

The SSE stream returns four types of events in sequence:

​
1. Thoughts Event

Provides insights into the query processing logic: 
data: {"type":"thoughts","data":{"filters":["headline contains 'engineer'"],"traits":["Profile mentions engineer"],"key_phrases":["engineer","engineering"],"metadata":"SQL construction notes"},"created":1748020550423}

​
2. SQL Event

Contains the generated SQL query: 
data: {"type":"sql","data":{"sql":"SELECT id AS OUTPUT_ID, headline, current_title FROM public.linkedin_profiles WHERE LOWER(headline) LIKE LOWER('%engineer%')"},"created":1748020553674}

​
3. Results Event

Contains the actual query results: 
data: {"type":"results","data":{"items":[{"id":"c0cc058f-0ef0-4ef5-bfea-fe0468d3814f","item":{"001_headline":"AI & VC Engineer","002_current_title":"Software Engineer","003_bio":"..."}}]},"created":1748020553784}

​
4. Close Event

Indicates the stream has completed: 
data: {"type":"close","data":{"complete":true},"created":1748020553784}

​
Consuming the SSE Stream

To consume the SSE stream in JavaScript: 
const eventSource = new EventSource('https://platform.datagyro.com/v1/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    query_string: "Engineers",
    dataset_id: "118",
    limit: 10
  })
});

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'thoughts':
      console.log('Processing insights:', data.data);
      break;
    case 'sql':
      console.log('Generated SQL:', data.data.sql);
      break;
    case 'results':
      console.log('Query results:', data.data.items);
      break;
    case 'close':
      console.log('Stream completed');
      eventSource.close();
      break;
  }
};

​
Error Handling

The API may return the following error responses:
  • 400 Bad Request: Invalid parameters were provided
  • 401 Unauthorized: Invalid or missing API key
  • 404 Not Found: The specified dataset was not found
  • 500 Server Error: An internal server error occurred
Error responses will include an error message and code: 
{
  "error": "Invalid dataset ID provided",
  "error_code": "INVALID_DATASET"
}

Authorizations

​
apikey
string
header
required

API key for authentication

Body

application/json
​
query_string
string
required

The search query to execute against the dataset

Example:

"Engineers"

​
dataset_id
string
required

Identifier for the dataset to query

Example:

"118"

​
limit
integer
default:10

Maximum number of results to return

Required range: 1 <= x <= 100
​
use_smaller_model
boolean
default:false

Option to use a smaller model for faster but potentially less accurate results

Response

Server-Sent Events stream with query processing updates

SSE stream with events containing JSON data