> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datagyro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Data

> Performs a query against a specified dataset with the given parameters

## 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

```bash theme={null}
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:

```javascript theme={null}
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:

```json theme={null}
{
  "error": "Invalid dataset ID provided",
  "error_code": "INVALID_DATASET"
}
```


## OpenAPI

````yaml POST /v1/query
openapi: 3.1.0
info:
  title: DataGyro API
  description: API for querying the DataGyro platform
  version: 1.0.0
  contact:
    name: DataGyro Support
    url: https://platform.datagyro.com/support
servers:
  - url: https://platform.datagyro.com
    description: Production server
security: []
paths:
  /v1/query:
    post:
      summary: Query the dataset
      description: Performs a query against a specified dataset with the given parameters
      operationId: queryDataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
            examples:
              engineers:
                value:
                  query_string: Engineers
                  dataset_id: '118'
                  limit: 10
                  use_smaller_model: false
      responses:
        '200':
          description: Server-Sent Events stream with query processing updates
          content:
            text/event-stream:
              schema:
                type: string
                description: SSE stream with events containing JSON data
              examples:
                thoughts_event:
                  summary: Thoughts event example
                  value: >+
                    data: {"type":"thoughts","data":{"filters":["headline
                    contains 'engineer'"],"traits":["Profile mentions
                    engineer"],"key_phrases":["engineer","engineering"],"metadata":"SQL
                    construction notes"},"created":1748020550423}

                sql_event:
                  summary: SQL event example
                  value: >+
                    data: {"type":"sql","data":{"sql":"SELECT id AS OUTPUT_ID,
                    headline FROM linkedin_profiles WHERE LOWER(headline) LIKE
                    LOWER('%engineer%')"},"created":1748020553674}

                results_event:
                  summary: Results event example
                  value: >+
                    data:
                    {"type":"results","data":{"items":[{"id":"123","item":{"headline":"Software
                    Engineer"}}]},"created":1748020553784}

                close_event:
                  summary: Close event example
                  value: >+
                    data:
                    {"type":"close","data":{"complete":true},"created":1748020553784}

        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKey: []
components:
  schemas:
    QueryRequest:
      type: object
      required:
        - query_string
        - dataset_id
      properties:
        query_string:
          type: string
          description: The search query to execute against the dataset
          example: Engineers
        dataset_id:
          type: string
          description: Identifier for the dataset to query
          example: '118'
        limit:
          type: integer
          description: Maximum number of results to return
          default: 10
          minimum: 1
          maximum: 100
        use_smaller_model:
          type: boolean
          description: >-
            Option to use a smaller model for faster but potentially less
            accurate results
          default: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        error_code:
          type: string
          description: Error code identifier
  securitySchemes:
    apiKey:
      type: apiKey
      name: apikey
      in: header
      description: API key for authentication

````