> ## Documentation Index > Fetch the complete documentation index at: https://docs.synq.io/llms.txt > Use this file to discover all available pages before exploring further. # PreviewSchedules > PreviewSchedules returns the next occurrences for one or more schedule expressions. Never fails at the RPC level; per-schedule errors are returned in the response items. Response items match request items by index. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/schedule/v1/preview openapi: 3.1.0 info: version: '1.0' title: SYNQ servers: - url: https://developer.synq.io - url: https://api.us.synq.io security: - bearerAuth: [] tags: - name: synq.incidents.v1.IncidentsService description: IncidentsService is a service for managing Incidents. - name: synq.auth.iam.v1.IamService - name: synq.agent.recon.v1.YamlService description: >- YamlService provides stateless conversion between YAML config format and proto. This is useful for UI editors that need to display/edit suite configs as YAML. - name: synq.agent.recon.v1.SuiteDeploymentService description: |- SuiteDeploymentService is the platform plane of reconciliation. SuiteConfigService is the developer/authoring sandbox (edit, version, run ad-hoc with your own credentials — preview-only, no Entity, no Run, no Issue). A deployment is what SYNQ actually runs on the workspace's behalf: a frozen snapshot of a suite config, mapped to workspace-level SYNQ integrations, optionally scheduled or triggerable by API. Identity: every deployment has a stable deployment_id (UUIDv7) assigned on first promote. It survives re-promotes, schedule/mapping changes, and pause/resume. Downstream AssetCommand / RunCommand publication keys off deployment_id so Entity identity does not fragment on promote churn. - name: synq.agent.sre.v1.FeatureRequestService description: >- FeatureRequestService allows MCP clients to submit feature requests when users encounter missing capabilities. This is a last-resort service — it should only be used when no existing tool can fulfill the user's request. - name: synq.agent.sre.v1.TriageService description: >- Service for managing issue triage operations, allowing LLM agents to conclude investigations and record evidence during the triage process. - name: synq.agent.sre.v1.LlmService description: Service for evaluating LLM requests and producing structured output. - name: synq.queries.v1.QueriesService description: |- QueriesService compiles and evaluates ResolverQL — the compact text query language used across Coalesce Quality to select entities — over the public API. ResolverQL is a string DSL (for example `with_type("TABLE")` or `in_folder(...)`); a structured `synq.queries.v1.Query` is its parsed, machine-readable form. This service is the bridge between the two and the read-only execution surface for both: - `TranslateResolverQl` compiles a ResolverQL expression into a structured `Query` without evaluating it — inspect it, validate it, or reuse it as a filter on another API (entity listing, folder browsing, ...). - `ResolveQuery` compiles a ResolverQL expression (or takes an already-structured `Query`), evaluates it against the catalog, and returns the matched entity ids. This is the general author -> resolve loop. - name: synq.queries.v1.NLQueryService description: >- NLQueryService generates structured Query protos from natural language descriptions using an LLM. - name: synq.domains.v1.DomainsService description: DomainsService can be used to manage domains. - name: synq.domains.members.v1.DomainMembersService description: DomainMembersService can be used to manage domain memberships. - name: synq.domains.v2.DomainsService description: >- DomainsService manages data domains — named areas of ownership that group the assets, data products and sub-domains belonging to one part of the business. Ids are opaque UUIDs supplied by the caller, which makes writes idempotent (a retried create converges instead of duplicating). Mutable fields are optional on Upsert: a field that is set is written, a field that is omitted is left unchanged. Pass the `etag` you last read to guard against overwriting a concurrent edit. A domain may contain other domains and data products, so membership resolution is recursive. Every write that adds such a reference — including a change of `parent_id` — is rejected if it would close a loop, so a definition can always be resolved in finite time. - name: synq.alerts.services.v1.AlertsService description: AlertsService provides operations for managing alert configurations. - name: synq.platforms.v1.PlatformsService description: PlatformsService is a service for managing Platforms and Integrations. - name: synq.dataproducts.v1.DataproductsService description: DataproductsService can be used to manage data products. - name: synq.dataproducts.v2.DataproductsService description: |- DataproductsService manages data products — named, owned groupings of data assets with a membership definition, a priority and an optional folder. Ids are opaque UUIDs supplied by the caller, which makes writes idempotent (a retried create converges instead of duplicating). Mutable fields are optional on Upsert: a field that is set is written, a field that is omitted is left unchanged. Pass the `etag` you last read to guard against overwriting a concurrent edit. A data product is a leaf in the reference graph — its definition may not reference another data product or domain — so membership resolution always terminates. - name: synq.owners.v1.OwnersService description: |- OwnersService manages owners and their ownerships — the "alert routing as code" surface. An owner is a named responsible party with notification channels (contacts); an ownership assigns a set of assets to an owner and configures the alerts routed to it. Owner is the resource, ownership its sub-resource: an ownership is meaningless without its owner, and deleting an owner deletes its ownerships. Ids are opaque UUIDs supplied by the caller, which makes writes idempotent (a retried create converges instead of duplicating). Mutable fields are optional on the Upsert calls: a set field is written, an omitted field is left unchanged. Pass the `etag` you last read to guard against overwriting a concurrent edit. Related: `synq.dataproducts.v2.DataproductsService` (an ownership can own a whole data product), `synq.alerts.v1.AlertsService` (how the configured alerts are reported), and `synq.users.v1.UsersService` (resolve the users behind `UserContact` and Slack/Teams mentions). - name: synq.extensions.atlan.workflows.v1.AtlanWorkflowService - name: synq.extensions.atlan.provider.v1.AtlanProviderService - name: synq.extensions.atlan.integrations.v1.AtlanIntegrationService - name: synq.git.commits.v1.CommitsService - name: synq.ingest.cloudwatch.v1.CloudwatchService - name: synq.ingest.dwh.v1.DwhService - name: synq.ingest.airflow.v1.AirflowLogsService - name: synq.ingest.openlineage.v1.OpenlineageService - name: synq.schedule.v1.ScheduleService description: ScheduleService provides schedule evaluation utilities. - name: synq.savedviews.v1.SavedViewsService description: >- SavedViewsService manages saved views — named, reusable selections over your entities (and other surfaces) with display configuration, sharing and per-user pinning. A saved view is owned by the user who created it. It can be kept private, shared with the whole workspace, or granted to specific users. Reads return, for the calling user, how each view relates to them (mine / shared / granted) and what they are allowed to do with it. Workspace administrators can manage any view in the workspace. - name: synq.datachecks.v1.TriggerService description: TriggerService provides synchronous execution of datachecks on entities. - name: synq.entities.executions.v2.EntityExecutionsService description: >- EntityExecutionsService provides read-only access to entity execution history. This service allows customers to retrieve information about all executions that happened on their entities, including execution status, timing, and messages. Use cases: - Retrieve execution history for specific entities - Filter executions by time range, status, or execution type - Get aggregated summaries of execution activity - Track execution trends and patterns - name: synq.datachecks.sqltests.v1.SqlTestsService description: SqlTestsService is a service for managing SqlTests. - name: synq.datachecks.testsuggestions.v1.TestSuggestionsService - name: synq.integrations.v1.IntegrationsService description: |- IntegrationsService manages connections from Coalesce Quality to your data systems (warehouses, databases, and transformation tools). Concurrency: every integration carries an opaque `etag`. Read it from `GetIntegration` / `ListIntegrations`, then pass it back on `UpdateIntegration` / `DeleteIntegration` to ensure you modify the version you last saw. A stale etag is rejected with ABORTED (HTTP 409). Omit the etag for last-write-wins. Quota: each workspace has a limit on the number of integrations. Creating beyond the limit is rejected with RESOURCE_EXHAUSTED. Secrets: credential fields (passwords, tokens, keys) are write-only. They are masked (returned empty) on every read. On update, omit a secret to keep it, send a new value to rotate it, or send an explicit empty string to clear it (where the field is `optional`). - name: synq.issues.v2.IssuesService description: IssuesService is a service for managing Issues. - name: synq.issues.issues.v1.IssuesService description: IssuesService is a service for managing Issues. - name: synq.monitors.history.v1.HistoryService - name: synq.monitors.info.v1.MonitorInfoService - name: synq.monitors.custom_monitors.v1.CustomMonitorsService - name: synq.monitors.predictions.v1.MonitorPredictionsService description: Access to anomaly detection model predictions and raw metric timeseries. - name: synq.monitors.automated_monitors.v1.DeploymentRulesService - name: synq.entities.checks.v1.ChecksCategoriesService description: |- ChecksCategoriesService lets workspace admins set explicit category overrides on individual checks. An explicit category is the authoritative category for a check — it takes precedence over the categories computed by the workspace's categorisation rules. It is a public API so customers can manage check categories programmatically; the same service is also mounted on the internal API. The workspace and the acting identity are always taken from the request context, never from the payload. - name: synq.entities.coordinates.v1.DatabaseCoordinatesService description: >- DatabaseCoordinatesService is a service for getting database coordinates of Entities. - name: synq.entities.orchestration.v1.OrchestrationService description: >- OrchestrationService provides information about orchestration relationships between entities. This includes relationships between Airflow tasks and transformation models (dbt, SQLMesh), as well as task-to-task dependencies. - name: synq.entities.constraints.v1.TableConstraintsService description: >- TableConstraintsService provides access to table constraint and index information. - name: synq.entities.impact.v1.ImpactService - name: synq.entities.resolve.v1.IdentifierResolveService description: >- IdentifierResolveService resolves identifiers to their Coalesce Quality paths and identities. - name: synq.entities.code.v1.CodeService description: >- CodeService is a service for retrieving code associated with entities in the system. It provides functionality to access and manage code artifacts such as SQL queries, Python scripts, dbt models, and other code configurations that are part of Coalesce Quality entities. - name: synq.entities.executions.v1.EntityExecutionsService description: 'Deprecated: Use [synq.entities.custom.v1.EntityExecutionsService] instead' - name: synq.entities.custom.v1.ChecksRelationshipsService - name: synq.entities.custom.v1.EntitiesService description: >- custom.EntitiesService is a service for managing custom entities. Entities can represent various data platform concepts such as services, consumers, applications or data pipelines that are not natively available in Coalesce Quality. Entities are identified by a unique identifier and can be created, updated, read and deleted. - name: synq.entities.custom.v1.RelationshipsService description: >- RelationshipsService allow management of relationships between entities. Relationships can be created, updated, and deleted between 2 custom entities, or between a custom entity and Coalesce Quality native entity.enum There is no option to create relationships between 2 Coalesce Quality native entities (dbt model, BI dashboard, etc.). - name: synq.entities.custom.v1.GroupsService description: >- It eliminates the need to keep state on client side to remember which assets were already created and which should be deleted. The server will keep track of the current state of the group and client can always send the intended new state. The server will calculate the diff and entities that are no longer present in the group will be removed. Example: 1. group has entities A, B, C at time t1 2. client sends group with entities B, C, D at time t2 3. server will remove entity A from the system and update the current state of the group to B, C, D The service is designed to be idempotent and can be called multiple times with the same state without causing any side effects. - name: synq.entities.custom.v1.EntityExecutionsService - name: synq.entities.custom.v1.FeaturesService - name: synq.entities.custom.v1.TypesService description: TypesService is a service for managing custom entity types. - name: synq.entities.lineage.v1.LineageService description: |- LineageService allows you to fetch: * Entity level lineage from a starting point of one or more entities. * Column Level lineage from a starting point of multiple columns of a single entity. - name: synq.entities.changes.v1.ChangesService description: >- ChangesService provides functionality to track and retrieve all types of changes to data entities. This unified service returns ALL change types for an entity: - Git commits: Changes to code files (dbt models, SQL files) tracked in version control - Schema changes: Database schema modifications (columns added/removed/changed) - SQL definition changes: View/materialized view definition updates detected by Coalesce Quality Changes are returned with structured metadata including: - For git commits: structured statistics (directories, file types, top changes) - For schema changes: detailed column-level diffs - For SQL changes: before/after SQL definitions Use cases: - "What changed in the last week for table X?" → Returns git commits, schema changes, SQL changes - "Show me all commits affecting this dbt model" → Returns git commits with lineage context - "What schema changes happened to this table?" → Returns schema changes detected by Coalesce Quality - name: synq.entities.sql_insights.v1.SqlInsightsService description: >- SqlInsightsService exposes analytical information about the SQL used across a workspace's entities. It answers questions such as "which SQL constructs are used in my warehouse, and how often" and "what SQL constructs does this specific entity use", without requiring the caller to re-parse any SQL. - name: synq.entities.annotations.v1.AnnotationsService description: >- AnnotationsService provides operations for managing and querying entity annotations. Annotations are key-value pairs that can be attached to entities for categorization and filtering. - name: synq.entities.status.v1.EntityIncidentsService description: EntityIncidentsService is the service which retrieves entity status. - name: synq.entities.status.v1.EntityIssuesService description: EntityIssuesService is the service which retrieves entity issues status. - name: synq.entities.folders.v1.FoldersService description: >- FoldersService discovers and browses the folder / containment hierarchy of the catalog: the roots data hangs from, the sub-folders under any folder, the folders a given entity lives in, and the entities contained in a folder. It is a read / navigation surface, not folder management — there are no create, move, or delete operations. Addressing: every folder has an opaque `folder_entity_id` (round-trip it verbatim) and a structured `FolderRef{root_entity_id, folders[]}` (the human-friendly form). Entities — both folder members and the ids you pass to `GetFolderOf` — are named by their opaque entity id, the same id used across the rest of the entities API. Depth footgun: membership is SHALLOW by default. `Browse` returns only the direct children of a folder, and `ListMembers` returns only the entities placed directly in the folder. Set `deep = true` (or raise `Browse.depth`) to recurse into sub-folders. - name: synq.entities.entities.v1.EntitiesService description: EntitiesService is a service for retriving any entity. - name: synq.entities.schemas.v1.SchemaMismatchesService description: >- SchemaMismatchesService provides access to schema drift information between data platform tables and their definitions (e.g., dbt models). - name: synq.entities.schemas.v1.SchemasService description: EntitiesService is a service for retriving any entity. paths: /api/schedule/v1/preview: post: tags: - synq.schedule.v1.ScheduleService summary: PreviewSchedules description: >- PreviewSchedules returns the next occurrences for one or more schedule expressions. Never fails at the RPC level; per-schedule errors are returned in the response items. Response items match request items by index. operationId: synq.schedule.v1.ScheduleService.PreviewSchedules requestBody: content: application/json: schema: $ref: '#/components/schemas/synq.schedule.v1.PreviewSchedulesRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/synq.schedule.v1.PreviewSchedulesResponse' components: schemas: synq.schedule.v1.PreviewSchedulesRequest: type: object properties: schedules: type: array items: $ref: '#/components/schemas/synq.schedule.v1.PreviewScheduleParams' maxItems: 100 description: Schedules to evaluate. An empty list returns an empty response. title: PreviewSchedulesRequest additionalProperties: false synq.schedule.v1.PreviewSchedulesResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/synq.schedule.v1.PreviewScheduleResult' description: Results matching the request schedules by index. title: PreviewSchedulesResponse additionalProperties: false synq.schedule.v1.PreviewScheduleParams: type: object properties: schedule: $ref: '#/components/schemas/synq.schedule.v1.Schedule' description: The schedule to evaluate. after: $ref: '#/components/schemas/google.protobuf.Timestamp' description: >- Starting point for computing occurrences. Defaults to now if not set. nullable: true limit: type: integer maximum: 100 minimum: 1 format: int32 description: Number of occurrences to return. Defaults to 7, maximum 100. nullable: true snap: $ref: '#/components/schemas/synq.schedule.v1.ScheduleSnap' description: >- Optional. When set, each computed occurrence is mapped to the nearest matching grid point before being returned, so the job co-fires with existing activity (e.g. a warehouse that is already awake) instead of triggering its own resume. When unset, occurrences are returned exactly as the schedule expression produces them. nullable: true title: PreviewScheduleParams required: - schedule additionalProperties: false description: Parameters for evaluating a single schedule. synq.schedule.v1.PreviewScheduleResult: type: object properties: occurrences: type: array items: $ref: '#/components/schemas/google.protobuf.Timestamp' description: The next occurrences in chronological order. Empty if error is set. error: type: string description: >- Error message if the schedule expression is invalid or cannot be evaluated. Empty on success. snapInfo: type: array items: $ref: '#/components/schemas/synq.schedule.v1.SnapInfo' description: >- Per-occurrence snap outcome, index-aligned with `occurrences`. Empty when snap was not requested. title: PreviewScheduleResult additionalProperties: false description: Result for a single schedule evaluation. synq.schedule.v1.Schedule: type: object allOf: - properties: timezone: type: string title: timezone minLength: 1 description: IANA timezone, e.g. "Europe/Warsaw", "America/New_York". - oneOf: - properties: cron: $ref: '#/components/schemas/synq.schedule.v1.CronSchedule' title: cron title: cron required: - cron - properties: ical: $ref: '#/components/schemas/synq.schedule.v1.ICalSchedule' title: ical title: ical required: - ical title: Schedule required: - timezone additionalProperties: false description: Schedule defines a recurring schedule with timezone context. google.protobuf.Timestamp: type: string examples: - '2023-01-15T01:30:15.01Z' - '2024-12-25T12:00:00Z' format: date-time description: >- A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D ) to obtain a formatter capable of generating timestamps in this format. synq.schedule.v1.ScheduleSnap: type: object allOf: - properties: tolerance: $ref: '#/components/schemas/google.protobuf.Duration' title: tolerance description: >- How far an occurrence may be moved to land on the grid. If the nearest eligible grid point is farther away than this, the occurrence is returned unmoved and flagged as not snapped (see SnapInfo). Unset or zero means an occurrence snaps only when it already lands exactly on a grid point. direction: $ref: '#/components/schemas/synq.schedule.v1.SnapDirection' title: direction description: >- Direction an occurrence is allowed to move. Unspecified behaves as NEAREST. - oneOf: - properties: fixedQuantum: $ref: '#/components/schemas/synq.schedule.v1.FixedQuantumGrid' title: fixed_quantum description: >- Snap onto a fixed-quantum grid (e.g. every 10 minutes from the Unix epoch, UTC). Useful for tidy round-minute fire times without coupling to integration activity. title: fixed_quantum required: - fixedQuantum - properties: integrationAnchor: $ref: '#/components/schemas/synq.schedule.v1.IntegrationAnchorGrid' title: integration_anchor description: >- Snap onto the shared warehouse-scrape grid for an integration, so the run co-fires with the periodic scrape and reuses the same warehouse wake instead of paying for another resume. title: integration_anchor required: - integrationAnchor title: ScheduleSnap additionalProperties: false description: >- ScheduleSnap maps each schedule occurrence onto a grid so runs line up with activity that is already happening, avoiding a separate warehouse resume. Pick one grid source and, optionally, how far an occurrence may move. synq.schedule.v1.SnapInfo: type: object properties: original: $ref: '#/components/schemas/google.protobuf.Timestamp' description: >- The occurrence as the schedule expression produced it, before snapping. snapped: type: boolean description: >- True if the occurrence was moved onto the grid. False if the nearest grid point was farther than the tolerance (or none was available), in which case the aligned `occurrences` entry equals `original`. title: SnapInfo additionalProperties: false description: >- SnapInfo records, for one occurrence, whether snapping moved it onto the grid. synq.schedule.v1.CronSchedule: type: object properties: expression: type: string minLength: 1 description: Standard cron expression (e.g. "0 */6 * * *"). title: CronSchedule required: - expression additionalProperties: false description: CronSchedule uses standard cron expression syntax. synq.schedule.v1.ICalSchedule: type: object properties: recurrenceRule: type: string minLength: 1 description: >- RFC 5545 RRULE recurrence rule (e.g. "FREQ=MONTHLY;BYDAY=TH;BYSETPOS=-1"). DTSTART should be set via the dtstart field below rather than inline in the rule. dtstart: $ref: '#/components/schemas/google.protobuf.Timestamp' description: >- Anchor time for the recurrence rule. Wall-clock time interpreted in the schedule's timezone. Defines when the schedule starts and aligns occurrences. If not set and no DTSTART is present in the recurrence_rule, defaults to now(). nullable: true title: ICalSchedule required: - recurrenceRule additionalProperties: false description: ICalSchedule uses RFC 5545 RRULE recurrence rules. google.protobuf.Duration: type: string format: duration description: |- A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years. # Examples Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td) # JSON Mapping In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s". synq.schedule.v1.SnapDirection: type: string title: SnapDirection enum: - SNAP_DIRECTION_UNSPECIFIED - SNAP_DIRECTION_NEAREST - SNAP_DIRECTION_FORWARD - SNAP_DIRECTION_BACKWARD description: >- SnapDirection constrains which way an occurrence may move to reach the grid. synq.schedule.v1.FixedQuantumGrid: type: object properties: quantum: $ref: '#/components/schemas/google.protobuf.Duration' description: Spacing between grid points, e.g. 10m. title: FixedQuantumGrid required: - quantum additionalProperties: false description: |- FixedQuantumGrid snaps onto a fixed-size grid anchored at the Unix epoch (1970-01-01T00:00:00Z): [epoch, epoch+quantum, epoch+2*quantum, ...]. synq.schedule.v1.IntegrationAnchorGrid: type: object properties: integrationId: type: string description: The integration whose scrape grid to align to. period: $ref: '#/components/schemas/google.protobuf.Duration' description: >- Spacing between grid points. When unset, the integration's configured scrape cadence is used — this is what actually resumes the warehouse once per tick. Set it only to override for unusual cases. nullable: true title: IntegrationAnchorGrid required: - integrationId additionalProperties: false description: >- IntegrationAnchorGrid snaps onto the shared, stable grid an integration's periodic warehouse scrape already fires on. Aligning to it lets a run reuse the same warehouse wake as the scrape. The integration is resolved in the caller's own workspace (taken from the authenticated identity, never from the request), and the caller must be authorized to read it — a token without integration read access is rejected. securitySchemes: bearerAuth: type: http scheme: bearer ````