Request Parameters Response Elements Errors Examples See Also

GetContextGraph

Queries the context graph with filtering, traversal, and pagination support.

Pagination note: nodes and edges are returned together as a coherent subgraph. Pagination cursors advance over nodes (the primary collection); each page includes all edges connecting nodes within that page. Callers should treat nodes as the paginated collection and edges as supplementary relationship data attached to those nodes.

Request Parameters

depth

How many hops to traverse out from the nodes matched by nodeFilters. 0 returns only the matched nodes themselves.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 3.

Required: No

edgeFilters

Criteria restricting which edges are returned.

Type: EdgeFilters object

Required: No

endTime

End of the time range (UTC), inclusive.

Type: Timestamp

Required: Yes

includeMetadata

Whether to return the metadata block, semantics included, on each node and edge. Off by default because it costs an extra lookup per returned node.

Type: Boolean

Required: No

maxEdgesPerNode

The maximum number of edges to return per node, bounding the fan-out of a densely connected node.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 50.

Required: No

maxResults

The maximum number of nodes to return in a single page.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: No

nextToken

Pagination token from a previous response, to retrieve the next page.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No

nodeFilters

Criteria restricting which nodes are returned.

Type: NodeFilters object

Required: No

startTime

Start of the time range (UTC), inclusive.

Type: Timestamp

Required: Yes

Response Elements

The following elements are returned by the service.

nextToken

Pagination token for the next page; absent when there are no more results.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

nodes

The page of nodes matching the request. This is the paginated collection.

Type: Array of Node objects

Array Members: Minimum number of 0 items. Maximum number of 1000 items.

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

The caller is not authorized to perform this action.

HTTP Status Code: 403

InternalServerException

An unexpected error occurred while processing the request.

errorCode: The error code associated with the internal error.

HTTP Status Code: 500

ThrottlingException

The request was throttled due to exceeding the allowed request rate.

retryAfterSeconds: The number of seconds to wait before retrying the request. Not always present.

HTTP Status Code: 429

ValidationException

A parameter is specified incorrectly.

errorCode: The error code associated with the validation failure.

HTTP Status Code: 400

Examples

Query a service and its immediate dependencies

The following example returns context graph nodes matching the filter and traverses one hop out to their direct dependencies, over a one-hour window. Payloads are shown as JSON; on the wire they are CBOR-encoded.

Sample Request


{
  "depth": 1,
  "endTime": "2026-09-16T01:00:00Z",
  "includeMetadata": false,
  "maxResults": 100,
  "nodeFilters": {
    "namespace": [
      "ecommerce"
    ],
    "nodeType": "SERVICE"
  },
  "startTime": "2026-09-16T00:00:00Z"
}

Sample Response


{
  "nextToken": "eyJvZmZzZXQiOjEwMH0=",
  "nodes": [
    {
      "edges": [
        {
          "edgeId": "edge:checkout-service->payments-service",
          "edgeType": "CALLS",
          "firstObservedAt": "2026-09-16T00:03:00Z",
          "from": "svc:checkout-service",
          "lastObservedAt": "2026-09-16T00:58:00Z",
          "operations": [
            "POST /charges"
          ],
          "signalTypes": [
            "TRACES"
          ],
          "sources": [
            "TELEMETRY"
          ],
          "to": "svc:payments-service"
        }
      ],
      "firstObservedAt": "2026-09-16T00:03:00Z",
      "lastObservedAt": "2026-09-16T00:58:00Z",
      "name": "checkout-service",
      "nodeId": "svc:checkout-service",
      "nodeProperties": {
        "cloudProvider": "aws",
        "namespace": "ecommerce",
        "region": "us-east-1",
        "sourceAccountId": "123456789012"
      },
      "nodeType": "SERVICE",
      "signalTypes": [
        "TRACES"
      ],
      "sources": [
        "TELEMETRY"
      ]
    },
    {
      "firstObservedAt": "2026-09-16T00:01:00Z",
      "lastObservedAt": "2026-09-16T00:59:00Z",
      "name": "payments-service",
      "nodeId": "svc:payments-service",
      "nodeProperties": {
        "cloudProvider": "aws",
        "namespace": "ecommerce",
        "region": "us-east-1",
        "sourceAccountId": "123456789012"
      },
      "nodeType": "SERVICE",
      "signalTypes": [
        "TRACES"
      ],
      "sources": [
        "TELEMETRY"
      ]
    }
  ]
}