Queries - Exulu IMP

Overview

All query operations in Exulu IMP follow consistent patterns. This reference covers both core type queries and the patterns that apply to dynamically generated queries.

Query patterns

Every resource type (core and dynamic) gets these query operations:

Operation	Purpose	Authentication required
`{type}ById`	Fetch single resource by ID	Yes
`{type}ByIds`	Fetch multiple resources by IDs	Yes
`{type}One`	Fetch single resource with filters	Yes
`{typePlural}Pagination`	Paginated list with filters	Yes
`{typePlural}Statistics`	Aggregate statistics	Yes

By ID queries

Pattern

{type}ById(id: ID!): {type}

Example

query {
  agentById(id: "agent-123") {
    id
    name
    description
    provider
    modelName
  }
}

Response

{
  "data": {
    "agentById": {
      "id": "agent-123",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries",
      "provider": "anthropic",
      "modelName": "claude-sonnet-4-5"
    }
  }
}

Error handling

{
  "errors": [
    {
      "message": "Record not found",
      "path": ["agentById"]
    }
  ],
  "data": {
    "agentById": null
  }
}

By IDs queries (batch)

Pattern

{type}ByIds(ids: [ID!]!): [{type}]!

Example

query {
  agentsByIds(ids: ["agent-1", "agent-2", "agent-3"]) {
    id
    name
    provider
  }
}

Response

{
  "data": {
    "agentsByIds": [
      {
        "id": "agent-1",
        "name": "Assistant 1",
        "provider": "openai"
      },
      {
        "id": "agent-2",
        "name": "Assistant 2",
        "provider": "anthropic"
      },
      {
        "id": "agent-3",
        "name": "Assistant 3",
        "provider": "google"
      }
    ]
  }
}

One (filtered) queries

Pattern

{type}One(
  filters: [Filter{Type}]
  sort: SortBy
): {type}

Example

query {
  agentOne(
    filters: [
      { name: { contains: "support" } }
      { provider: { eq: "anthropic" } }
    ]
    sort: { field: "createdAt", direction: DESC }
  ) {
    id
    name
    description
  }
}

With complex filters

query {
  userOne(
    filters: [
      {
        or: [
          { email: { contains: "@example.com" } }
          { email: { contains: "@company.com" } }
        ]
      }
      { super_admin: { eq: false } }
    ]
  ) {
    id
    name
    email
  }
}

Pagination queries

Pattern

{typePlural}Pagination(
  limit: Int = 10
  page: Int = 1
  filters: [Filter{Type}]
  sort: SortBy
): {Type}PaginationResult

Basic pagination

query {
  agentsPagination(limit: 20, page: 1) {
    items {
      id
      name
      provider
    }
    pageInfo {
      currentPage
      pageCount
      itemCount
      hasPreviousPage
      hasNextPage
    }
  }
}

With filters and sorting

query {
  agentsPagination(
    limit: 50
    page: 2
    filters: [
      { provider: { in: ["anthropic", "openai"] } }
      { createdAt: { gte: "2025-01-01T00:00:00Z" } }
    ]
    sort: { field: "name", direction: ASC }
  ) {
    items {
      id
      name
      provider
      createdAt
    }
    pageInfo {
      currentPage
      pageCount
      hasNextPage
    }
  }
}

Response

{
  "data": {
    "agentsPagination": {
      "items": [
        {
          "id": "agent-1",
          "name": "Assistant A",
          "provider": "anthropic",
          "createdAt": "2025-01-15T10:00:00Z"
        }
      ],
      "pageInfo": {
        "currentPage": 2,
        "pageCount": 5,
        "hasNextPage": true
      }
    }
  }
}

Statistics queries

Pattern

{typePlural}Statistics(
  filters: [Filter{Type}]
  groupBy: String
  limit: Int = 10
): [StatisticsResult]!

type StatisticsResult {
  group: String!
  count: Int!
}

Total count

query {
  agentsStatistics {
    group
    count
  }
}

Response:

{
  "data": {
    "agentsStatistics": [
      {
        "group": "total",
        "count": 42
      }
    ]
  }
}

Group by field

query {
  agentsStatistics(
    groupBy: "provider"
    limit: 10
  ) {
    group
    count
  }
}

Response:

{
  "data": {
    "agentsStatistics": [
      { "group": "anthropic", "count": 15 },
      { "group": "openai", "count": 12 },
      { "group": "google", "count": 8 },
      { "group": "cerebras", "count": 7 }
    ]
  }
}

With filters

query {
  agent_sessionsStatistics(
    filters: [
      { createdAt: { gte: "2025-01-01T00:00:00Z" } }
    ]
    groupBy: "agent"
    limit: 5
  ) {
    group
    count
  }
}

Vector search queries

Available for contexts with embedders configured.

Pattern

{contextPlural}VectorSearch(
  query: String!
  method: VectorMethodEnum!
  itemFilters: [Filter{Context}]
  cutoffs: SearchCutoffs
  expand: SearchExpand
): {context}VectorSearchResult

Cosine distance search

query {
  documentationVectorSearch(
    query: "How do I deploy the application?"
    method: cosineDistance
    cutoffs: { cosineDistance: 0.7 }
  ) {
    chunks {
      chunk_content
      chunk_cosine_distance
      item_name
      item_id
    }
    context {
      name
      embedder
    }
    query
    method
  }
}

Hybrid search (vector + full-text)

query {
  documentationVectorSearch(
    query: "authentication setup"
    method: hybridSearch
    cutoffs: {
      cosineDistance: 0.8
      tsvector: 0.1
    }
  ) {
    chunks {
      chunk_content
      chunk_hybrid_score
      chunk_cosine_distance
      chunk_fts_rank
      item_name
    }
  }
}

With filters and expansion

query {
  documentationVectorSearch(
    query: "database migration"
    method: cosineDistance
    itemFilters: [
      { category: { eq: "tutorials" } }
    ]
    cutoffs: { cosineDistance: 0.75 }
    expand: { before: 1, after: 2 }
  ) {
    chunks {
      chunk_content
      chunk_index
      chunk_cosine_distance
      item_name
      item_id
    }
  }
}

Full-text search only

query {
  documentationVectorSearch(
    query: "installation guide"
    method: tsvector
  ) {
    chunks {
      chunk_content
      chunk_fts_rank
      item_name
    }
  }
}

Chunk by ID queries

Fetch individual chunks from vector search contexts.

Pattern

{context}ChunkById(id: ID!): {context}VectorSearchChunk

Example

query {
  documentationChunkById(id: "chunk-123") {
    chunk_content
    chunk_index
    chunk_id
    chunk_source
    chunk_metadata
    chunk_created_at
    item_id
    item_name
    item_external_id
  }
}

Special queries

Providers

List all available agent providers.

query {
  providers {
    items {
      id
      name
      description
      provider
      providerName
      modelName
      type
    }
  }
}

Tools

List available tools for agents.

query {
  tools(
    search: "weather"
    category: "api"
    limit: 20
    page: 1
  ) {
    items {
      id
      name
      description
      category
      type
      config
    }
    total
    page
    limit
  }
}

Tool categories

query {
  toolCategories
}

Response:

{
  "data": {
    "toolCategories": [
      "agents",
      "api",
      "contexts",
      "database",
      "file-processing",
      "web"
    ]
  }
}

Contexts

List all available semantic search contexts.

query {
  contexts {
    items {
      id
      name
      description
      active
      slug
      embedder {
        id
        name
        config {
          name
          description
          default
        }
        queue
      }
      fields
      sources {
        id
        name
        description
        config {
          schedule
          queue
          retries
          params {
            name
            description
            default
          }
        }
      }
      processor {
        name
        description
        queue
        trigger
        timeoutInSeconds
        generateEmbeddings
      }
    }
  }
}

Context by ID

query {
  contextById(id: "documentation") {
    id
    name
    description
    embedder {
      name
      queue
    }
    fields
    configuration
  }
}

Evaluations

List available evaluation functions.

query {
  evals {
    items {
      id
      name
      description
      llm
      config {
        name
        description
      }
    }
  }
}

Rerankers

List available reranking models.

query {
  rerankers {
    items {
      id
      name
      description
    }
  }
}

Unique prompt tags

query {
  getUniquePromptTags
}

Response:

{
  "data": {
    "getUniquePromptTags": [
      "greeting",
      "support",
      "technical",
      "sales"
    ]
  }
}

Job queries

Jobs by queue

query {
  jobs(
    queue: eval_runs
    statusses: [active, waiting, failed]
    page: 1
    limit: 50
  ) {
    items {
      id
      name
      state
      data
      returnvalue
      stacktrace
      finishedOn
      processedOn
      attemptsMade
      failedReason
      timestamp
    }
    pageInfo {
      currentPage
      pageCount
      itemCount
      hasNextPage
    }
  }
}

Queue information

query {
  queue(queue: eval_runs) {
    name
    concurrency {
      worker
      queue
    }
    timeoutInSeconds
    ratelimit
    isMaxed
    isPaused
    jobs {
      paused
      completed
      failed
      waiting
      active
      delayed
    }
  }
}

Response:

{
  "data": {
    "queue": {
      "name": "eval_runs",
      "concurrency": {
        "worker": 2,
        "queue": 10
      },
      "timeoutInSeconds": 180,
      "ratelimit": 100,
      "isMaxed": false,
      "isPaused": false,
      "jobs": {
        "paused": 0,
        "completed": 245,
        "failed": 12,
        "waiting": 5,
        "active": 2,
        "delayed": 0
      }
    }
  }
}

Workflow queries

Workflow schedule

Check if a workflow has a scheduled execution.

query {
  workflowSchedule(workflow: "workflow-123") {
    id
    schedule
    next
    iteration
  }
}

Response:

{
  "data": {
    "workflowSchedule": {
      "id": "workflow-123-schedule",
      "schedule": "0 9 * * *",
      "next": "2025-01-16T09:00:00Z",
      "iteration": 5
    }
  }
}

Advanced filtering examples

String operators

query {
  agentsPagination(
    filters: [
      { name: { contains: "assistant" } }
      { description: { contains: "support" } }
    ]
  ) {
    items {
      id
      name
    }
  }
}

Number operators

query {
  statisticsPagination(
    filters: [
      { count: { gte: 100, lte: 1000 } }
    ]
  ) {
    items {
      label
      count
    }
  }
}

Date operators

query {
  agentsPagination(
    filters: [
      {
        createdAt: {
          gte: "2025-01-01T00:00:00Z"
          lte: "2025-01-31T23:59:59Z"
        }
      }
    ]
  ) {
    items {
      id
      name
      createdAt
    }
  }
}

AND logic

query {
  agentsPagination(
    filters: [
      {
        and: [
          { provider: { eq: "anthropic" } }
          { name: { contains: "claude" } }
        ]
      }
    ]
  ) {
    items {
      id
      name
    }
  }
}

OR logic

query {
  agentsPagination(
    filters: [
      {
        or: [
          { provider: { eq: "anthropic" } }
          { provider: { eq: "openai" } }
        ]
      }
    ]
  ) {
    items {
      id
      name
      provider
    }
  }
}

Complex nested logic

query {
  agentsPagination(
    filters: [
      {
        and: [
          {
            or: [
              { provider: { eq: "anthropic" } }
              { provider: { eq: "openai" } }
            ]
          }
          { name: { contains: "assistant" } }
          {
            createdAt: {
              gte: "2025-01-01T00:00:00Z"
            }
          }
        ]
      }
    ]
  ) {
    items {
      id
      name
      provider
    }
  }
}

Field selection

Request only the fields you need:

Minimal fields

query {
  agentsPagination(limit: 100) {
    items {
      id
      name
    }
  }
}

All basic fields

query {
  agentById(id: "agent-123") {
    id
    name
    description
    backend
    type
    provider
    modelName
    createdAt
    updatedAt
  }
}

With nested objects

query {
  agentById(id: "agent-123") {
    id
    name
    capabilities {
      text
      images
      files
    }
    rateLimit {
      name
      rate_limit {
        time
        limit
      }
    }
    workflows {
      enabled
      queue {
        name
      }
    }
  }
}

With RBAC

query {
  agentById(id: "agent-123") {
    id
    name
    RBAC {
      type
      users {
        id
        rights
      }
      roles {
        id
        rights
      }
    }
  }
}

Query variables

Use variables for dynamic queries:

query GetAgent($id: ID!) {
  agentById(id: $id) {
    id
    name
    description
  }
}

Variables:

{
  "id": "agent-123"
}

With filters

query GetAgents(
  $limit: Int!
  $page: Int!
  $provider: String
) {
  agentsPagination(
    limit: $limit
    page: $page
    filters: [
      { provider: { eq: $provider } }
    ]
  ) {
    items {
      id
      name
    }
    pageInfo {
      currentPage
      hasNextPage
    }
  }
}

Variables:

{
  "limit": 20,
  "page": 1,
  "provider": "anthropic"
}

Query aliases

Use aliases to fetch the same resource with different parameters:

query {
  anthropicAgents: agentsPagination(
    filters: [{ provider: { eq: "anthropic" } }]
  ) {
    items {
      id
      name
    }
  }

  openaiAgents: agentsPagination(
    filters: [{ provider: { eq: "openai" } }]
  ) {
    items {
      id
      name
    }
  }
}

Fragments

Reuse field selections with fragments:

fragment AgentBasics on agent {
  id
  name
  description
  provider
  modelName
}

query {
  agent1: agentById(id: "agent-1") {
    ...AgentBasics
  }

  agent2: agentById(id: "agent-2") {
    ...AgentBasics
  }
}

Next steps

Mutations

Learn about mutation operations

Core types

Explore predefined types

Dynamic types

Learn about context types

Introduction

Back to API overview

​Overview

​Query patterns

​By ID queries

​Pattern

​Example

​Response

​Error handling

​By IDs queries (batch)

​Pattern

​Example

​Response

​One (filtered) queries

​Pattern

​Example

​With complex filters

​Pagination queries

​Pattern

​Basic pagination

​With filters and sorting

​Response

​Statistics queries

​Pattern

​Total count

​Group by field

​With filters

​Vector search queries

​Pattern

​Cosine distance search

​Hybrid search (vector + full-text)

​With filters and expansion

​Full-text search only

​Chunk by ID queries

​Pattern

​Example

​Special queries

​Providers

​Tools

​Tool categories

​Contexts

​Context by ID

​Evaluations

​Rerankers

​Unique prompt tags

​Job queries

​Jobs by queue

​Queue information

​Workflow queries

​Workflow schedule

​Advanced filtering examples

​String operators

​Number operators

​Date operators

​AND logic

​OR logic

​Complex nested logic

​Field selection

​Minimal fields

​All basic fields

​With nested objects

​With RBAC

​Query variables

​With filters

​Query aliases

​Fragments

​Next steps

Mutations

Core types

Dynamic types

Introduction

Overview

Query patterns

By ID queries

Pattern

Example

Response

Error handling

By IDs queries (batch)

Pattern

Example

Response

One (filtered) queries

Pattern

Example

With complex filters

Pagination queries

Pattern

Basic pagination

With filters and sorting

Response

Statistics queries

Pattern

Total count

Group by field

With filters

Vector search queries

Pattern

Cosine distance search

Hybrid search (vector + full-text)

With filters and expansion

Full-text search only

Chunk by ID queries

Pattern

Example

Special queries

Providers

Tools

Tool categories

Contexts

Context by ID

Evaluations

Rerankers

Unique prompt tags

Job queries

Jobs by queue

Queue information

Workflow queries

Workflow schedule

Advanced filtering examples

String operators

Number operators

Date operators

AND logic

OR logic

Complex nested logic

Field selection

Minimal fields

All basic fields

With nested objects

With RBAC

Query variables

With filters

Query aliases

Fragments

Next steps