Insomnia logo
  • Documentation
  • Get Started for Free
    • Introduction to Insomnia
    • Install Insomnia
    • Send Your First Request
    • Import and Export Data
    • Environment Variables
    • Global Environments
    • Insomnia Accounts
    • Forgotten Passphrase
    • Managing E2EE (End-to-End Encryption)
    • Organizations
    • Enable Enterprise membership
    • Configuring EE SSO
    • Integrating Insomnia Enterprise with Okta SAML 2.0
    • Integrating Insomnia Enterprise with Okta OpenID Connect
    • Integrating Insomnia Enterprise with Microsoft Azure/Entra ID SAML 2.0
    • Insomnia Whitelisting Guide for Enterprise Users
    • Transfer enterprise organizations and license
    • Configuring SCIM
    • Multiple Owners
    • Manage Domains
    • Invite Controls
    • Storage Controls
    • Session Report
    • Insomnia Subscriptions
    • Insomnia Subscription Management
    • Scratch Pad Tutorial
    • Requests
    • Responses
    • Request Collections
    • Request Timeouts
    • Chaining Requests
    • Post CSV Data
    • SOAP Requests
    • gRPC
    • WebSocket Support
    • Get Started with Documents
    • Design Documents
    • Linting
    • GraphQL for OpenAPI
    • Migrate from Designer
    • Unit Testing
    • Stress Testing
    • Insomnia Storage Options Guide
    • Sync with Insomnia Cloud
    • Sync with Git
    • Key Security Features
    • Security Standards
    • Signup and Authentication
    • Analytics Collected
    • End to End Data Encryption
    • Software Bill of Materials
    • Verifying Build Provenance for Signed Insomnia Binaries
    • Authentication
    • Client Certificates
    • Collection Runner
    • Generate Code Snippet
    • Cookie Management
    • Encoding
    • GraphQL Queries
    • Run in Insomnia Button
    • Key Maps
    • Proxy
    • Folder-level settings
    • Introduction to Plugins
    • Context Object Reference
    • Template Tags
    • Hooks and Actions
    • Custom Themes
    • AI Runner
    • FAQ
    • Application Data
    • SSL Validation
    • Password Recovery
    • Introduction to Inso CLI
    • Install Inso CLI
    • CLI Command Reference
      • inso run test
      • inso run collection
      • inso lint spec
      • inso export spec
      • inso script
      • Using Custom Linting with Inso CLI
    • Configuration
    • Inso CLI on Docker
    • Software Bill of Materials
    • Verifying Signatures for Signed Inso CLI Images
    • Verifying Inso CLI Build Provenance
      • Verifying Build Provenance for Signed Inso CLI Images
      • Verifying Build Provenance for Signed Inso CLI Binaries
    • Continuous Integration
    • Insomnia Pre-request Script Overview
    • Insomnia After-Response Script Overview
    • Secret Environment Variables
    • External Vault Integration (Enterprise feature)
    • Insomnia API Mocking Overview
    • Enterprise Login Report

GraphQL Queries

GraphQL is a query language for APIs that uses a type system to help with correctness and maintainability. Insomnia makes use of this type system to provide auto-completion and linting of GraphQL queries. This article will explain how to create and execute GraphQL queries within Insomnia.

Using GraphQL

Creating a GraphQL request in Insomnia is easy. It can be done by either selecting the GraphQL request type during creation or by changing the body type of an existing request using the body menu.

Once this is done, you can fill in the query and variables section of the query.

Query Section

The query is the only required field of a GraphQL request. Queries can include arguments, comments, fragment, as well as any other valid query constructs. While editing the query, Insomnia will provide auto-completion and errors messages based on the API schema.

Note: GraphQL queries cannot include Insomnia templating but variables can.

Variables Section

GraphQL variables are defined in the Query Variables section below the query. Variables must be defined as a valid JSON object and can include Environment Variables and Template Tags if desired. If the variables section is left empty the variables attribute will not be included in the request payload.

Construct the Request Payload

Insomnia automatically constructs the payload of a GraphQL request and saves it whenever the query or variables sections are modified. There are three possible attributes that make up a GraphQL request.

  • query (string): The GraphQL query to be sent.
  • variables (object): An optional object of variables to be included with the query.
  • operationName (string): An optional operation name, populated automatically using the first named query if one exists.

The following is an example of a GraphQL request payload that makes use of all three parameters.

{
    "query": "query MyQuery($id: string) { thing(id: $id) { id name created } }",
    "variables": {
        "id": "thing_123"
    },
    "operationName": "MyQuery"
}

Note: It may be useful to know that this is how Insomnia stores the request body behind the scenes. Try converting the body type to JSON and back and see for yourself.

Schema Fetching

To provide auto-complete and error checking of GraphQL queries, Insomnia automatically fetches the schema by sending an introspection query. This query is performed both when switching to a new GraphQL request in the app or when various properties of the request are modified (eg. URL).

Note: All attributes of the request (authentication, headers, etc) are also sent with the introspection query

Documentation Browser

Insomnia supports the ability to browse the documentation for the current GraphQL endpoint.

There are three ways to show the documentation pane.

  1. Click Show Documentation in the Schema dropdown near the query.
  2. Hover over a field and click within the popup documentation.
  3. Control+click (on Mac) a field within a query.
Edit this page
Report an issue
    COMPANY
  • Insomnia
  • Blog
  • Changelog
  • Pricing
  • Careers
    PRODUCTS
  • Insomnia
  • Inso (CLI)
    RESOURCES
  • Sign In
  • Documentation
  • Support
    LEGAL
  • Privacy Policy
  • Terms & Conditions
© Kong Inc. 2021