Execute and inspect results

You need a Semogram account with access to the workspace and a project in it. Definition and binding changes, query publication, execution and assertion review require their respective permissions. External reads and writes also require the selected plugin installation's credentials and access.

Start a read

You need a published query, permission to execute it and access under its bindings' policies. For the demo orders query, the input is empty and the desired page limit is 10. Use the actual query UUID; the draft version ID is not its resource ID.

Open the published query, choose Execute, provide the declared inputs and page options. Inspect the resulting job/page rather than treating submission as success.

Execute the published Demo orders query with empty inputs and limit 10. Wait for a completed result if queued. Compare IDs and values with the known two-order fixture and report release, source endpoints, completeness, consistency and diagnostics.

Use a workspace API key with queries:execute. Set SEMOGRAM_API_KEY in your shell and replace UUID placeholders with accessible resource IDs.

HTTP API

curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_UUID>/ontology/queries/<QUERY_UUID>/execute" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "input": {},
  "options": {
    "limit": 10,
    "offset": 0
  }
}
JSON

MCP tool call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_execute",
    "arguments": {
      "projectId": "<PROJECT_UUID>",
      "queryId": "<QUERY_UUID>",
      "request": {
        "input": {},
        "options": {
          "limit": 10,
          "offset": 0
        }
      }
    }
  }
}

HTTP returns 202 for queued/running work and 200 for a succeeded page. Query execution is a read; it does not approve assertions or materialize new facts.

Continue a queued job

Call the same execute action using the same input/release/caller and options.jobId from the returned meta.job.id. This polls/resumes the bounded result job. Do not fabricate an ID or use a pipeline job's ID here.

Execute request body for continuation

{"input":{},"options":{"jobId":"<RETURNED_QUERY_JOB_UUID>","limit":10}}

For MCP, put that body under request alongside queryId. A query's public jobs route exposes cancellation, not a generic GET polling action; poll via execute as above.

Continue result pages

Use meta.nextCursor exactly as returned with the same inputs, caller and release. Do not combine cursor with jobId or a nonzero offset. Default page size is 100, maximum 1000. Offsets are a separate start/page mechanism; stable cursors are preferable for continuing the same result snapshot.

Result jobs currently expire after one hour. Inspect returned expiresAt rather than assuming a token lasts forever. If expired, start a new execution and compare its source observations; new execution is not the same snapshot.

Inspect more than rows

Field	What it tells you
status	Queued, running or succeeded
data.rows / rowCount	This page's records and count
meta.totalRowCount / hasMore / nextCursor	Result paging state
meta.completeness	Complete, partial or unknown under execution limits
meta.consistency	Snapshot, mixed or live_unpinned source semantics
meta.sourceSnapshots	Backend snapshots actually observed
meta.resolvedBindings	Terms, binding IDs, methods and endpoints used
meta.job / expiresAt	Continuation job and retention window
diagnostics	Missing/partial/ambiguous or other execution details

A result snapshot makes pages consistent within one job. It does not promise a distributed transaction over all live systems. A complete result is complete within its query scope and supported bounds; it is not all business knowledge.

Default runtime bounds are 10,000 result rows and 100,000 rows per source read, configurable by operators. Reaching a source bound is reported as partial. Do not conclude a missing order does not exist when the result is partial or filtered.

Cancellation and failures

HTTP DELETE /api/v1/projects/<PROJECT_UUID>/queries/<QUERY_UUID>/jobs/<JOB_UUID> (queries:execute) cancels an active caller-owned job. MCP query_cancel uses queryId, optional version and request with the original input and options.jobId. Completed/failed/canceled jobs are not active cancellation targets.

Inspect error categories: invalid input/output schema, not published/retired, permission failure, changed contract, expired result, scalar ambiguity or downstream unavailability. Resolve the named cause before repeating execution; changing page size does not fix a permission or semantic conflict.