Context Graph commands

This topic covers the postman context-graph command for the Postman CLI.

Your team’s Context Graph is Postman’s map of your team’s APIs and the dependencies between them. Use the postman context-graph commands to ask it natural-language questions, such as what depends on a given API. The team a query runs against is derived from your credentials, so there’s no workspace or team option.

These commands require authentication. Sign in with the postman login command, or pass a Postman API key with --api-key.

To give a coding agent instructions for using the Postman CLI itself, such as for code generation, use postman context instead.

`postman context-graph ask`

Submits a natural-language question about your team’s Context Graph and returns an ask ID, which you check later with postman context-graph status. Use --wait to block until the answer arrives and print it. This is usually how you’ll want to run it, whether manually or using automation. Omit --wait only if you want to submit several asks without waiting, or need to poll on your own schedule. If an ask happens to finish before this command returns, it prints the answer instead of an ID.

Usage

postman context-graph ask <query> [options]

<query>

The natural-language question to ask about your team’s Context Graph.

Options

--wait

Waits for the answer and prints it inline, instead of returning an ask ID.

--no-include-answer

Returns the ask record without including the answer inline.

--max-steps <count>

The maximum number of reasoning steps the service may take. Accepts a positive integer.

--interval <seconds>

Defaults to 2

How often to poll for the answer, in seconds. Accepts a value from 0.5 to 3600. Requires --wait.

--timeout <seconds>

Defaults to 300

How long to wait for the answer before giving up, in seconds, up to 86400 (24 hours). Requires --wait. If the wait times out, the ask keeps running in Postman, and you can check it later with postman context-graph status.

--json

Prints the ask record as JSON for machine-readable output, instead of a table.

--api-key <key>

Authenticates with a Postman API key instead of your postman login session. Falls back to the POSTMAN_API_KEY environment variable.

Examples

postman context-graph ask "What depends on billing-api?" --wait
postman context-graph ask "Which APIs are in the graph?"
postman context-graph ask "What depends on billing-api?" --wait --interval 5 --timeout 120

Exit codes

Code	Meaning
`0`	The ask completed, or was accepted without `--wait`.
`1`	A request or CLI error, such as an authentication failure, a network error, or an invalid option value.
`2`	The ask reached a failed state.
`4`	The `--wait` timeout elapsed before the ask finished. The ask keeps running, so you can check it later with `postman context-graph status`.

`postman context-graph status`

Checks on an ask submitted with postman context-graph ask, without waiting. Provide the ask ID that ask returned. If the ask has finished, it prints the answer. Otherwise, it reports that the ask is still in progress.