Queries
Every read operation in Golden Reports goes through a single GraphQL endpoint. This page documents every field on the root Query type, grouped by the resource it returns.
Overview
POST https://api.goldenreports.dev/graphql
All queries require a bearer token (see Authentication). Object identifiers are UUID scalars and timestamps are returned as ISO 8601 strings on the DateTime scalar.
Most lookups by identifier accept a UUID!. Most list operations accept optional paging, filter, and sort arguments and return a cursor-based *NodesPage envelope.
Pagination, filtering, and sorting
List queries (workspaces, reports, dataContexts, dataSources, creditTransactions) share the same shape. Each one accepts a paging: PagingInput argument and returns a *NodesPage envelope:
- Name
paging.cursor- Type
- ID
- Description
Opaque cursor returned by the previous page. Omit on the first call.
- Name
paging.limit- Type
- Int
- Description
Page size. Defaults to the server-side limit; cap depends on the resource.
- Name
items- Type
- [T!]!
- Description
The current page of nodes.
- Name
cursor- Type
- ID
- Description
Cursor to pass back as
paging.cursorfor the next page.nullonce exhausted.
Sorting uses the same envelope across resources: a sort: { fields: [{ field, direction }] } input where field is one of NAME or CREATED_AT and direction is ASC or DESC.
Paginating workspaces
query Workspaces($cursor: ID) {
workspaces(
paging: { cursor: $cursor, limit: 25 }
sort: { fields: [{ field: NAME, direction: ASC }] }
) {
items { id name }
cursor
}
}
Workspaces
Workspaces are the top-level container for projects, data contexts, data sources, and reports.
List workspaces
Returns a paged list of every workspace the caller can see.
Arguments
- Name
paging- Type
- PagingInput
- Description
Cursor pagination — see Pagination.
- Name
sort- Type
- WorkspaceSortingInput
- Description
Sort by
NAMEorCREATED_AT(ASC or DESC).
Returns WorkspaceNodesPage!.
Request
query {
workspaces {
items {
id
name
description
projects {
id
name
}
}
cursor
}
}
Response
{
"data": {
"workspaces": {
"items": [
{
"id": "8b3f…",
"name": "Acme Reporting",
"description": null,
"projects": [{ "id": "1ad2…", "name": "Default" }]
}
],
"cursor": null
}
}
}
Get a workspace
Returns a single workspace by id, or null if it doesn't exist or the caller can't see it.
Arguments
- Name
id- Type
- UUID!
- Description
The workspace identifier.
Workspace fields
- Name
id- Type
- UUID!
- Description
- Workspace identifier.
- Name
name- Type
- String!
- Description
- Display name.
- Name
description- Type
- String
- Description
- Optional description.
- Name
projects- Type
- [Project!]!
- Description
- All projects in this workspace.
Request
query Workspace($id: UUID!) {
workspace(id: $id) {
id
name
description
projects {
id
name
description
}
}
}
There's no top-level project or projects query. Walk to projects through workspace.projects or report.project.
Reports
Reports are render-spec + GraphQL-query bundles that produce HTML or Excel output.
List reports
Arguments
- Name
filter.codes- Type
- [String!]
- Description
Filter by one or more report codes.
- Name
filter.projectId- Type
- UUID
- Description
Restrict to a single project.
- Name
paging- Type
- PagingInput
- Description
- Cursor pagination.
- Name
sort- Type
- ReportSortingInput
- Description
- Sort by
NAMEorCREATED_AT.
Returns ReportNodesPage!.
Request
query Reports($projectId: UUID) {
reports(filter: { projectId: $projectId }) {
items {
id
code
name
renderSpecType
version
createdAt
}
cursor
}
}
Get a report
Arguments
- Name
id- Type
- UUID!
- Description
- The report identifier.
Report fields
- Name
id- Type
- UUID!
- Description
- Report identifier.
- Name
code- Type
- String!
- Description
- Stable, human-friendly code used by
embeddedReportandexportedReport.
- Name
name- Type
- String!
- Description
- Display name.
- Name
description- Type
- String
- Description
- Optional description.
- Name
renderSpecType- Type
- RenderSpecType!
- Description
HTMLorEXCEL.
- Name
renderSpecData- Type
- JSON
- Description
- Renderer-specific layout configuration.
- Name
graphQlQuery- Type
- String
- Description
- The GraphQL query the report executes against its data context.
- Name
variables- Type
- JSON
- Description
- Internal variables resolved at render time.
- Name
parameters- Type
- JSON
- Description
- User-facing parameter definitions (what callers can override).
- Name
version- Type
- Int!
- Description
- Monotonically increasing version, bumped on every save.
- Name
createdAt- Type
- DateTime!
- Description
- Creation timestamp.
- Name
lastModifiedAt- Type
- DateTime
- Description
- Last modification timestamp.
- Name
project- Type
- Project!
- Description
- The owning project.
- Name
dataContext- Type
- DataContext!
- Description
- The data context the report queries against.
- Name
createdBy- Type
- User!
- Description
- User who created the report.
- Name
lastModifiedBy- Type
- User
- Description
- User who last modified the report.
Request
query Report($id: UUID!) {
report(id: $id) {
id
code
name
renderSpecType
parameters
dataContext { id name }
project { id name }
}
}
Rendering & export
Embedded report
Renders a report to HTML for in-page embedding. Returns an HTML payload plus a short-lived session token suitable for streaming follow-up requests (e.g. interactive parameters).
Arguments
- Name
code- Type
- String!
- Description
- The report's
code.
- Name
parameters- Type
- JSON
- Description
- Runtime parameter overrides keyed by parameter name.
Returns GetEmbeddedReportResult
- Name
html- Type
- String
- Description
- Rendered HTML content.
- Name
sessionId- Type
- ID
- Description
- Render session identifier.
- Name
sessionToken- Type
- String
- Description
- Short-lived session authentication token.
Request
query Embed($code: String!, $params: JSON) {
embeddedReport(code: $code, parameters: $params) {
html
sessionId
sessionToken
}
}
Exported report
Exports a report to PDF or Excel. Returns a presigned download URL. Provide either pdf or excel options — the option you provide selects the output format.
Arguments
- Name
code- Type
- String!
- Description
- The report's
code.
- Name
parameters- Type
- JSON
- Description
- Runtime parameter overrides.
- Name
pdf- Type
- PdfExportOptionsInput
- Description
paperSize(A4,LETTER,LEGAL,A3),orientation(PORTRAIT,LANDSCAPE), and optionalmargins.
- Name
excel- Type
- ExcelExportOptionsInput
- Description
Optional
sheetNamefor the produced workbook.
Returns GetExportedReportResult
- Name
downloadUrl- Type
- String
- Description
- Presigned URL for the exported file.
Request
query ExportPdf($code: String!) {
exportedReport(
code: $code
pdf: { paperSize: A4, orientation: PORTRAIT }
) {
downloadUrl
}
}
Templates & themes
List templates
Returns every report template available to the tenant. Templates seed new reports through createReport.
Template fields
- Name
id- Type
- UUID!
- Description
- Template identifier.
- Name
name- Type
- String!
- Description
- Display name.
- Name
description- Type
- String!
- Description
- Long-form description.
- Name
renderSpecType- Type
- RenderSpecType!
- Description
HTMLorEXCEL.
- Name
category- Type
- TemplateCategory!
- Description
USE_CASEorSAMPLE.
- Name
enabled- Type
- Boolean!
- Description
- Whether the template is currently selectable.
- Name
thumbnailUrl- Type
- String
- Description
- Optional thumbnail URL.
- Name
icon- Type
- String
- Description
- Optional inline SVG icon.
Request
query {
templates {
id
name
category
renderSpecType
enabled
}
}
List themes
Returns every report theme available to the tenant. Themes are CSS payloads applied to HTML renders.
ReportTheme fields
- Name
id- Type
- UUID!
- Description
- Theme identifier.
- Name
code- Type
- String!
- Description
- Machine-readable code.
- Name
name- Type
- String!
- Description
- Display name.
- Name
value- Type
- String!
- Description
- The CSS content of the theme.
- Name
description- Type
- String
- Description
- Optional description.
- Name
active- Type
- Boolean!
- Description
- Whether the theme is enabled.
Request
query {
themes { id code name active }
}
Data contexts
A data context is a versioned schema + GraphQL query layer that sits on top of one or more data sources. Reports execute their graphQlQuery against a data context. Drafts are mutable; publishing creates an immutable DataContextVersion.
List data contexts
Arguments
- Name
filter.codes- Type
- [String!]
- Description
- Filter by one or more data context codes.
- Name
filter.projectId- Type
- UUID
- Description
- Restrict to a single project.
- Name
paging- Type
- PagingInput
- Description
- Cursor pagination.
- Name
sort- Type
- DataContextSortingInput
- Description
- Sort by
NAMEorCREATED_AT.
Returns DataContextNodesPage!.
Request
query {
dataContexts(paging: { limit: 25 }) {
items {
id
code
name
revision
lastPublishedVersionId
}
cursor
}
}
Get a data context
Returns the current draft state of a data context.
DataContext fields
- Name
id- Type
- UUID!
- Description
- Data context identifier.
- Name
code- Type
- String!
- Description
- Stable code.
- Name
name- Type
- String!
- Description
- Display name.
- Name
description- Type
- String
- Description
- Optional description.
- Name
schema- Type
- String!
- Description
- SDL of the GraphQL schema the data context exposes to reports.
- Name
designerState- Type
- JSON
- Description
- Opaque designer-tool state.
- Name
revision- Type
- Int!
- Description
- Current draft revision — increments on every auto-save.
- Name
draftId- Type
- UUID!
- Description
- Identifier of the live draft document.
- Name
lastPublishedVersionId- Type
- UUID
- Description
- Most recently published version, if any.
- Name
lock- Type
- DataContextLockState
- Description
- Current editing lock, if held — see Locking.
- Name
dataSources- Type
- [DataSource!]!
- Description
- Data sources bound to this draft.
- Name
versions- Type
- [DataContextVersion!]!
- Description
- All published versions.
- Name
latestVersion- Type
- DataContextVersion
- Description
- Most recent published version, or
null.
- Name
draftRevisions- Type
- [DataContextDraftRevision!]!
- Description
- Journal of draft revisions you can roll back to.
- Name
project- Type
- Project!
- Description
- Owning project.
Request
query DC($id: UUID!) {
dataContext(id: $id) {
id
name
revision
schema
lock {
holder { userId userName }
expiresAt
}
latestVersion {
id
number
publishedAt
}
}
}
Get a published version
Returns a single immutable DataContextVersion by id.
Arguments
- Name
id- Type
- UUID!
- Description
- Version identifier.
DataContextVersion fields
- Name
id- Type
- UUID!
- Description
- Version identifier.
- Name
dataContextId- Type
- UUID!
- Description
- Parent data context.
- Name
number- Type
- Int!
- Description
- Sequential version number (starts at 1).
- Name
name- Type
- String!
- Description
- Snapshot of the data context name at publish time.
- Name
schema- Type
- String!
- Description
- SDL frozen at publish time.
- Name
designerState- Type
- JSON
- Description
- Designer state at publish time.
- Name
publishedAt- Type
- DateTime!
- Description
- When this version was published.
- Name
publishedBy- Type
- User!
- Description
- Publishing user.
- Name
dataSources- Type
- [DataSource!]!
- Description
- Data sources bound at publish time.
Request
query V($id: UUID!) {
dataContextVersion(id: $id) {
id
number
name
publishedAt
publishedBy { id email }
}
}
Get a draft revision
Returns one entry from a data context's draft revision journal — useful for previewing or rolling back to a specific auto-save.
Arguments
- Name
id- Type
- UUID!
- Description
- Draft revision identifier.
Request
query R($id: UUID!) {
dataContextDraftRevision(id: $id) {
id
revision
capturedAt
capturedBy { id displayName }
}
}
Generate mock data
Runs a GraphQL query against a data context's schema and returns synthetic data shaped to match. Handy for previewing reports without hitting live sources.
Arguments
- Name
dataContextId- Type
- UUID!
- Description
- Data context whose schema to use.
- Name
query- Type
- String!
- Description
- A GraphQL query string to mock.
- Name
count- Type
- Int
- Description
- Number of rows to generate.
Returns MockDataResult
- Name
data- Type
- JSON!
- Description
- Generated rows as a JSON array.
- Name
rowCount- Type
- Int!
- Description
- How many rows were returned.
Request
query Mock($id: UUID!, $q: String!) {
mockData(dataContextId: $id, query: $q, count: 50) {
data
rowCount
}
}
Data sources
A data source is a configured connection to a database, file system, or third-party API. Data sources are referenced by data contexts.
List data sources
Arguments
- Name
filter.codes- Type
- [String!]
- Description
- Filter by data source codes.
- Name
filter.includeDeleted- Type
- Boolean
- Description
- When
true, include soft-deleted rows. Defaults tofalse.
- Name
filter.includeInactive- Type
- Boolean
- Description
- When
true, includeactive: falserows. Defaults tofalse.
- Name
paging- Type
- PagingInput
- Description
- Cursor pagination.
- Name
sort- Type
- DataSourceSortingInput
- Description
- Sort by
NAMEorCREATED_AT.
Returns DataSourceNodesPage!.
Request
query {
dataSources {
items {
id
code
name
active
connector { code name }
health {
status
errorCode
latencyMs
lastCheckedAt
}
}
cursor
}
}
Get a data source
Arguments
- Name
id- Type
- UUID!
- Description
- Data source identifier.
DataSource fields
- Name
id- Type
- UUID!
- Description
- Identifier.
- Name
code- Type
- String!
- Description
- Machine-readable code.
- Name
name- Type
- String!
- Description
- Display name.
- Name
description- Type
- String
- Description
- Optional description.
- Name
configuration- Type
- JSON!
- Description
- Connector-specific configuration. Secret fields are returned redacted.
- Name
active- Type
- Boolean!
- Description
- Whether the data source is enabled.
- Name
monitoringEnabled- Type
- Boolean!
- Description
- Whether automatic health monitoring is on.
- Name
createdAt- Type
- DateTime!
- Description
- Creation timestamp.
- Name
lastModifiedAt- Type
- DateTime
- Description
- Last modification timestamp.
- Name
deletedAt- Type
- DateTime
- Description
- Soft-deletion timestamp, or
null.
- Name
connector- Type
- ConnectorDefinition!
- Description
- The connector implementation.
- Name
health- Type
- DataSourceHealth
- Description
- Latest health snapshot — see Subscriptions.
- Name
createdBy- Type
- User!
- Description
- Creator.
- Name
lastModifiedBy- Type
- User
- Description
- Last modifier.
Request
query DS($id: UUID!) {
dataSource(id: $id) {
id
name
configuration
connector { code name }
health {
status
latencyMs
latencySamples {
timestamp
latencyMs
}
}
}
}
Introspect a data source
Lists the schemas, tables, views, and functions exposed by a configured data source. Use this to discover what's available when wiring up a data context.
Arguments
- Name
dataSourceId- Type
- UUID!
- Description
- Data source identifier.
- Name
artifactKindFilter- Type
- String
- Description
Limit results to a single artifact kind (e.g.
TABLE,VIEW,FUNCTION).
Returns IntrospectResult with a list of ArtifactNamespaces; each namespace contains Artifacts with name, kind, fields, parameters, and returnType.
Request
query Introspect($id: UUID!) {
introspectDataSource(dataSourceId: $id) {
namespaces {
name
artifacts {
name
kind
fields {
name
dataType
nullable
primaryKey
}
}
}
}
}
Connectors
List connectors
Returns every connector implementation available to the tenant. A connector is the type of integration (e.g. Postgres, BigQuery); a data source is a configured instance of one.
ConnectorDefinition fields
- Name
id- Type
- UUID!
- Description
- Connector identifier.
- Name
code- Type
- String!
- Description
- Machine-readable code.
- Name
name- Type
- String!
- Description
- Display name.
- Name
description- Type
- String
- Description
- Optional description.
- Name
configSchema- Type
- JSON
- Description
- JSON Schema describing the connector configuration.
- Name
active- Type
- Boolean!
- Description
- Whether the connector is enabled.
Request
query {
connectors {
id
code
name
configSchema
active
}
}
Artifact kinds for a connector
Returns the artifact kinds (e.g. TABLE, VIEW, FUNCTION) a given connector exposes.
Arguments
- Name
connectorId- Type
- UUID!
- Description
- Connector identifier.
Request
query Kinds($id: UUID!) {
connectorArtifactKinds(connectorId: $id) {
kind
displayName
description
supportsFields
}
}
Credits
Render operations consume credits. The credits API exposes the current balance and a paginated transaction history.
Credit balance
Returns the tenant's current credit balance.
CreditBalance fields
- Name
tenantId- Type
- UUID!
- Description
- Tenant identifier.
- Name
balance- Type
- Long!
- Description
- Current token balance.
Request
query {
creditBalance {
balance
}
}
Credit transactions
Returns paginated credit transactions for the current tenant.
Arguments
- Name
paging- Type
- PagingInput
- Description
- Cursor pagination.
CreditTransaction fields
- Name
id- Type
- UUID!
- Description
- Transaction identifier.
- Name
amount- Type
- Long!
- Description
- Token amount — positive for top-ups, negative for usage.
- Name
balanceAfter- Type
- Long!
- Description
- Balance snapshot immediately after this transaction.
- Name
type- Type
- String!
- Description
Purchase,Usage, orAdjustment.
- Name
description- Type
- String
- Description
- Human-readable description.
- Name
externalReference- Type
- String
- Description
- External reference (e.g. Stripe payment intent ID).
- Name
createdAt- Type
- DateTime!
- Description
- When the transaction occurred.
- Name
userId- Type
- UUID
- Description
- User who triggered the transaction.
Request
query {
creditTransactions(paging: { limit: 50 }) {
items {
id
amount
balanceAfter
type
createdAt
}
cursor
}
}