diff --git a/content/billing/concepts/product-billing/github-copilot.md b/content/billing/concepts/product-billing/github-copilot.md index 3b137b320445..604b99b05fef 100644 --- a/content/billing/concepts/product-billing/github-copilot.md +++ b/content/billing/concepts/product-billing/github-copilot.md @@ -79,10 +79,12 @@ For more information about {% data variables.copilot.copilot_coding_agent %}, se ### What happens if you have used up your monthly quota? -If you run out of free Actions minutes or free premium requests, and you have set up a payment method for billing, you will be charged at the normal rates for additional minutes and premium requests. See [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions) and [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/monitoring-usage-and-entitlements/about-premium-requests#additional-premium-requests). +If you run out of free Actions minutes or free premium requests, and you have set up a payment method and are not limited by a budget, you will be charged at the normal rates for additional minutes and premium requests. See [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions) and [AUTOTITLE](/copilot/concepts/billing/copilot-requests#what-if-i-run-out-of-premium-requests). If you run out of free minutes or premium requests, and you have _not_ set up billing, a message is displayed explaining why {% data variables.product.prodname_copilot_short %} cannot work on the task. +{% data reusables.copilot.zero-budget-changes %} See [AUTOTITLE](/copilot/how-tos/premium-requests/manage-for-enterprise). + ### Monitoring your use of Actions minutes and premium requests You can track your monthly usage of {% data variables.product.prodname_actions %} minutes and premium requests, to help you get the most value from your {% data variables.product.prodname_copilot_short %} plan. See [AUTOTITLE](/enterprise-cloud@latest/billing/managing-billing-for-your-products/managing-billing-for-github-actions/viewing-your-github-actions-usage) and [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/understanding-and-managing-copilot-usage/monitoring-your-copilot-usage-and-entitlements). diff --git a/content/billing/tutorials/set-up-budgets.md b/content/billing/tutorials/set-up-budgets.md index 8e0047f283e5..4fd9e8b34996 100644 --- a/content/billing/tutorials/set-up-budgets.md +++ b/content/billing/tutorials/set-up-budgets.md @@ -104,7 +104,7 @@ As the owner of an enterprise or organization account, or as a billing manager, ### Editing or deleting a budget ->[!IMPORTANT] Deleting a budget may remove any limits on spending, depending on your other existing budgets. For example, deleting the only budget that limits {% data variables.product.prodname_copilot_short %} premium requests allows for unlimited usage. +>[!IMPORTANT] Deleting a budget may remove any limits on spending, depending on your other existing budgets. You can edit or delete a budget at any time, but you cannot change the scope of a budget after creating it. diff --git a/content/copilot/concepts/billing/billing-for-spark.md b/content/copilot/concepts/billing/billing-for-spark.md index 6a2ebc5cd878..4339b3e9379d 100644 --- a/content/copilot/concepts/billing/billing-for-spark.md +++ b/content/copilot/concepts/billing/billing-for-spark.md @@ -19,7 +19,7 @@ contentType: concepts ## Billing for {% data variables.product.prodname_spark_short %} app creation -Each prompt consumes 4 premium requests, which draw from your plan's premium request allowance. If you or an administrator has set a budget for premium requests over your plan's allowance, additional premium requests beyond your plan’s included amount are billed at {% data variables.copilot.additional_premium_requests %} per request, meaning that one prompt to {% data variables.product.prodname_spark_short %} would cost **$0.16**. See [AUTOTITLE](/copilot/concepts/copilot-billing/understanding-and-managing-requests-in-copilot). +Each prompt consumes 4 premium requests, which draw from your plan's premium request allowance. If you have enabled premium requests over your plan's allowance, additional premium requests beyond your plan’s included amount are billed at {% data variables.copilot.additional_premium_requests %} per request, meaning that one prompt to {% data variables.product.prodname_spark_short %} would cost **$0.16**. See [AUTOTITLE](/copilot/concepts/copilot-billing/understanding-and-managing-requests-in-copilot). ## Billing and limits for {% data variables.product.prodname_spark_short %} app deployment diff --git a/content/copilot/concepts/billing/copilot-requests.md b/content/copilot/concepts/billing/copilot-requests.md index 2fc06fd7b4f9..8806100c08ef 100644 --- a/content/copilot/concepts/billing/copilot-requests.md +++ b/content/copilot/concepts/billing/copilot-requests.md @@ -68,15 +68,12 @@ Unused requests for the previous month do not carry over to the following month. If you're on a **paid plan** and use all of your premium requests, you can still use {% data variables.product.prodname_copilot_short %} with one of the included models for the rest of the month. This is subject to change. Response times for the included models may vary during periods of high usage. Requests to the included models may be subject to rate limiting. See [AUTOTITLE](/copilot/concepts/rate-limits). -If you need more premium requests beyond your monthly allowance, you can: +If you need more premium requests beyond your monthly allowance: -* Set a spending limit for additional premium requests. See [AUTOTITLE](/billing/managing-your-billing/using-budgets-control-spending). -* Upgrade your individual subscription to a higher plan. -* If you're an enterprise owner, edit the default $0 budget or upgrade members to {% data variables.copilot.copilot_enterprise_short %}. See [AUTOTITLE](/copilot/how-tos/premium-requests/manage-for-enterprise). +* For an individual subscription, set a budget for additional premium requests or upgrade to a higher plan. See [AUTOTITLE](/billing/managing-your-billing/using-budgets-control-spending). +* If you're an enterprise or organization owner, ensure that the "Premium request paid usage" policy is enabled and that extra spending is not prevented by a budget. See [AUTOTITLE](/copilot/how-tos/premium-requests/manage-for-enterprise). -These actions can be taken by enterprise owners, organization owners, billing managers, and personal account users. - -> [!IMPORTANT] By default, all budgets are set to zero and premium requests over the allowance are rejected unless a budget has been created. Additional premium requests beyond your plan’s included amount are billed at {% data variables.copilot.additional_premium_requests %} per request. +{% data reusables.copilot.zero-budget-changes %} ## Model multipliers diff --git a/content/copilot/get-started/choose-enterprise-plan.md b/content/copilot/get-started/choose-enterprise-plan.md index 9227837a7630..fc7a7cb9ae6a 100644 --- a/content/copilot/get-started/choose-enterprise-plan.md +++ b/content/copilot/get-started/choose-enterprise-plan.md @@ -70,7 +70,7 @@ Each {% data variables.product.prodname_copilot_short %} plan includes a per-use By ensuring members have access to enough premium requests, you can drive real business outcomes, such as reducing your backlog with {% data variables.copilot.copilot_coding_agent %}, accelerating pull requests with {% data variables.copilot.copilot_code-review_short %}, or increasing code quality with suggestions from more specialized models. -Regardless of your plan, you can set a spending limit for premium requests over your plan's allowance. Premium requests over the allowance will be charged at a rate of {% data variables.copilot.additional_premium_requests %} per request, with an additional multiplier applied to certain models. +Regardless of your plan, you can enable or disable premium requests over your plan's allowance. Premium requests over the allowance will be charged at a rate of {% data variables.copilot.additional_premium_requests %} per request, with an additional multiplier applied to certain models. ## Making a decision diff --git a/content/copilot/how-tos/manage-and-track-spending/index.md b/content/copilot/how-tos/manage-and-track-spending/index.md index 08f78cb70edc..125752cdccb7 100644 --- a/content/copilot/how-tos/manage-and-track-spending/index.md +++ b/content/copilot/how-tos/manage-and-track-spending/index.md @@ -8,7 +8,7 @@ topics: - Copilot children: - /monitor-premium-requests - - /manage-for-your-enterprise + - /manage-request-allowances - /manage-company-spending redirect_from: - /copilot/how-tos/premium-requests diff --git a/content/copilot/how-tos/manage-and-track-spending/manage-company-spending.md b/content/copilot/how-tos/manage-and-track-spending/manage-company-spending.md index 34b31fcc73bb..8442a0b5cc49 100644 --- a/content/copilot/how-tos/manage-and-track-spending/manage-company-spending.md +++ b/content/copilot/how-tos/manage-and-track-spending/manage-company-spending.md @@ -39,9 +39,9 @@ This report includes all premium request usage by user, both within and beyond t ### Granting more premium requests to members -By default, enterprises have a $0 budget for the Premium Request SKU. This means that when users exhaust their allowance, they cannot make any more premium requests for the rest of the month. Deleting this budget allows for **unlimited spending**. +Your organization or enterprise's policies and budgets determine whether users can use premium requests over their included allowance. See [AUTOTITLE](/copilot/how-tos/premium-requests/manage-for-enterprise). -To change the default budget or increase members' base allowance, see [AUTOTITLE](/copilot/how-tos/premium-requests/manage-for-enterprise). +{% data reusables.copilot.zero-budget-changes %} ## Mapping spending to groups of users @@ -56,7 +56,7 @@ For more information, see [AUTOTITLE](/billing/tutorials/use-cost-centers). You can set a monthly budget on {% data variables.product.prodname_copilot %} spending. * For {% data variables.product.prodname_copilot_short %} **licenses**, a budget is for monitoring purposes only and will not prevent usage beyond the budgeted amount. However, you will receive notifications by email when spending exceeds certain percentages of the budget you've set. -* For {% data variables.product.prodname_copilot_short %} **premium requests**, you can choose to stop usage once the budget amount is reached. The default $0 budget for enterprises already does this. +* For {% data variables.product.prodname_copilot_short %} **premium requests**, you can choose to stop usage once the budget amount is reached. To create a budget, see [AUTOTITLE](/billing/managing-your-billing/using-budgets-control-spending#editing-or-deleting-a-budget). diff --git a/content/copilot/how-tos/manage-and-track-spending/manage-for-your-enterprise.md b/content/copilot/how-tos/manage-and-track-spending/manage-request-allowances.md similarity index 53% rename from content/copilot/how-tos/manage-and-track-spending/manage-for-your-enterprise.md rename to content/copilot/how-tos/manage-and-track-spending/manage-request-allowances.md index 24685061c9c6..23606be79c36 100644 --- a/content/copilot/how-tos/manage-and-track-spending/manage-for-your-enterprise.md +++ b/content/copilot/how-tos/manage-and-track-spending/manage-request-allowances.md @@ -1,8 +1,8 @@ --- -title: Managing the premium request allowance for users in your enterprise -shortTitle: Manage for your enterprise -intro: 'Change the default spending limit or upgrade users to {% data variables.copilot.copilot_enterprise_short %}.' -permissions: Enterprise owners +title: Managing the premium request allowance for your organization or enterprise +shortTitle: Manage request allowances +intro: 'Configure policies and budgets for premium requests, or upgrade users to {% data variables.copilot.copilot_enterprise_short %}.' +permissions: Enterprise owners and organization owners versions: feature: copilot topics: @@ -13,38 +13,47 @@ redirect_from: - /copilot/how-tos/premium-requests/manage-for-enterprise - /copilot/how-tos/spending/manage-for-enterprise - /copilot/how-tos/spending/manage-for-your-enterprise + - /copilot/how-tos/manage-and-track-spending/manage-for-your-enterprise contentType: how-tos --- -Each {% data variables.product.prodname_copilot_short %} plan includes a per-user allowance for premium requests. To learn more about premium requests, see [AUTOTITLE](/copilot/concepts/copilot-billing/requests-in-github-copilot). For allowances per plan, see [AUTOTITLE](/copilot/get-started/plans-for-github-copilot#comparing-copilot-plans). +Each {% data variables.product.prodname_copilot_short %} plan includes a per-user allowance for premium requests. If enabled, requests over the allowance are billed to your organization or enterprise. To learn more about premium requests, see [AUTOTITLE](/copilot/concepts/copilot-billing/requests-in-github-copilot). For allowances per plan, see [AUTOTITLE](/copilot/get-started/plans-for-github-copilot#comparing-copilot-plans). -By default, every enterprise has a $0 budget for the Premium Request SKU. Unless this budget is edited or deleted, your enterprise will have **no extra costs** for premium requests: when one of your licensed users exhausts the allowance in their plan, the user's premium requests will be rejected for the rest of the month. +Your organization or enterprise's policies and budgets determine whether users can use premium requests over their included allowance: -![Screenshot of the enterprise budgets page, with the default budget: a $0 budget for the Premium Request SKU.](/assets/images/help/copilot/enterprise-premium-request-budget.png) +* The **Premium request paid usage** policy determines whether users can surpass their included allowance. This policy is enabled by default. +* If your enterprise or organization has a budget that caps usage of the **Premium Request SKU**, additional requests are blocked once the budget amount is reached for the billing period. -You can edit or delete this budget to grant extra requests to all your licensed members. If you want to grant extra requests to certain users only, you can upgrade those users to {% data variables.copilot.copilot_enterprise_short %}. +You can increase the allowance for users by ensuring the policy is enabled, editing your budgets, or upgrading users to {% data variables.copilot.copilot_enterprise_short %}. + +{% data reusables.copilot.zero-budget-changes %} ## Prerequisites * Before making changes, download a usage report to see which developers are frequently hitting the limit or using a significant number of requests over the allowance. You may want to contact these users to understand their use cases and requirements. See [Downloading a monthly usage report](/copilot/how-tos/monitoring-your-copilot-usage-and-entitlements#downloading-a-monthly-usage-report). * If a user receives licenses from multiple enterprises or standalone organizations, the user must select a billing entity to use premium requests. See [Managing premium request billing with multiple {% data variables.product.prodname_copilot_short %} licenses](/copilot/managing-copilot/monitoring-usage-and-entitlements/monitoring-your-copilot-usage-and-entitlements#managing-premium-request-billing-with-multiple-copilot-licenses). -## Changing the budget for all members +## Setting a policy for paid usage + +By default, premium requests over the allowance are enabled for organizations and enterprises. This allows for uninterrupted use of premium requests, unless you have a budget that caps spending on the Premium Request SKU. + +You can set the policy for an enterprise or a standalone organization. -To enable premium requests over the allowance for everyone, you can: +1. Navigate to the policy settings for your enterprise or organization. See [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) or [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies). +1. Next to "Premium request paid usage", select the policy for your organization or enterprise. -* Delete the default $0 budget to allow **unlimited spending on premium requests** for all users. -* Edit the "Budget amount" of the default $0 budget to set **a non-zero total spending limit** for premium requests in your enterprise. +## Updating budgets -For instructions, see [AUTOTITLE](/billing/managing-your-billing/using-budgets-control-spending#editing-or-deleting-a-budget). +1. Ensure the "Premium request paid usage" policy is enabled. See [Setting a policy for paid usage](#setting-a-policy-for-paid-usage). +1. Check the budgets for your enterprise or organizations, and edit or delete any budgets that "stop usage when budget limit is reached" for the Premium Request SKU. See [AUTOTITLE](/billing/managing-your-billing/using-budgets-control-spending#editing-or-deleting-a-budget). ->[!NOTE] Creating new budgets without deleting the $0 budget does not override the $0 budget. If **any** applicable budget with "Stop usage when budget limit is reached" enabled is exhausted, additional premium requests are blocked. +Creating new budgets without deleting an existing budget does not override the existing budget. If **any** applicable budget with "Stop usage when budget limit is reached" enabled is exhausted, additional premium requests are blocked. ## Upgrading users to {% data variables.copilot.copilot_enterprise_short %} -You can upgrade certain users to increase their base allowance of premium requests. +An enterprise owner can upgrade certain users to increase their base allowance of premium requests. ->[!TIP] {% data variables.copilot.copilot_business_short %} users who make make more than 800 premium requests per month would save money with a {% data variables.copilot.copilot_enterprise_short %} license. +>[!TIP] {% data variables.copilot.copilot_business_short %} users who make more than 800 premium requests per month would save money with a {% data variables.copilot.copilot_enterprise_short %} license. 1. Create a new organization in your enterprise. See [AUTOTITLE](/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise#creating-a-new-organization). 1. Add the users who need more premium requests to the new organization. @@ -64,6 +73,7 @@ You can set a higher budget for premium requests over the allowance for specific At a high level, the required steps are: -1. Delete the default $0 budget. +1. Ensure the "Premium request paid usage" policy is enabled. See [Setting a policy for paid usage](#setting-a-policy-for-paid-usage). +1. Delete the default $0 budget if it applies to your organization or enterprise. 1. Create a new budget for the users who need a higher allowance. For example, create an organization or cost center containing just these users, then create a Premium Request SKU budget for the organization or cost center. 1. Create a separate, more restrictive budget that covers every other {% data variables.product.prodname_copilot_short %} user in your enterprise. You will likely need to integrate with the API to ensure that this budget covers new users as they are added to your enterprise. diff --git a/content/copilot/how-tos/manage-and-track-spending/monitor-premium-requests.md b/content/copilot/how-tos/manage-and-track-spending/monitor-premium-requests.md index 69b347434ceb..e7469f015c28 100644 --- a/content/copilot/how-tos/manage-and-track-spending/monitor-premium-requests.md +++ b/content/copilot/how-tos/manage-and-track-spending/monitor-premium-requests.md @@ -87,8 +87,7 @@ You can use the following strategies to maximize the value of your premium reque * **Setting a budget**. Set a budget to track your overages and receive alerts when you reach 75%, 90%, or 100% of your budget. See [AUTOTITLE](/billing/managing-your-billing/preventing-overspending#managing-budgets-for-your-personal-account). - >[!NOTE] - > By default, all budgets are set to zero and premium requests over the allowance are rejected unless a budget has been created. + {% data reusables.copilot.zero-budget-changes %} * **Monitor your usage regularly**. Check your usage in your {% data variables.product.github %} account settings to see how many premium requests you’ve used. This helps you plan how much you can use for the rest of the month. diff --git a/content/graphql/guides/forming-calls-with-graphql.md b/content/graphql/guides/forming-calls-with-graphql.md index 223cbeb2b178..21b786568eb7 100644 --- a/content/graphql/guides/forming-calls-with-graphql.md +++ b/content/graphql/guides/forming-calls-with-graphql.md @@ -49,7 +49,7 @@ If you access {% data variables.product.github %} at a different domain, such as ## Communicating with GraphQL -Because GraphQL operations consist of multiline JSON, GitHub recommends using the [Explorer](/graphql/guides/using-the-explorer) to make GraphQL calls. You can also use `curl` or any other HTTP-speaking library. +Because GraphQL operations consist of multiline JSON, GitHub recommends using the [GraphQL Clients](/graphql/guides/using-graphql-clients) to make GraphQL calls. You can also use `curl` or any other HTTP-speaking library. In REST, [HTTP verbs](/rest#http-verbs) determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is `POST`. The exception is an [introspection query](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), which is a simple `GET` to the endpoint. For more information on GraphQL versus REST, see [AUTOTITLE](/graphql/guides/migrating-from-rest-to-graphql). diff --git a/content/graphql/guides/index.md b/content/graphql/guides/index.md index f27999c5904d..91f5b3d88a55 100644 --- a/content/graphql/guides/index.md +++ b/content/graphql/guides/index.md @@ -14,7 +14,7 @@ children: - /forming-calls-with-graphql - /using-global-node-ids - /migrating-from-rest-to-graphql - - /using-the-explorer + - /using-graphql-clients - /using-pagination-in-the-graphql-api - /managing-enterprise-accounts - /using-the-graphql-api-for-discussions diff --git a/content/graphql/guides/managing-enterprise-accounts.md b/content/graphql/guides/managing-enterprise-accounts.md index 2a99fc1a601f..4b00abbb3e5c 100644 --- a/content/graphql/guides/managing-enterprise-accounts.md +++ b/content/graphql/guides/managing-enterprise-accounts.md @@ -39,10 +39,7 @@ For a list of the fields available with the Enterprise Accounts API, see [AUTOTI ## Getting started using GraphQL for enterprise accounts -Follow these steps to get started using GraphQL to manage your enterprise accounts: -* Authenticating with a {% data variables.product.pat_generic %} -* Choosing a GraphQL client or using the GraphQL Explorer -* Setting up Insomnia to use the GraphQL API +See [AUTOTITLE](/graphql/guides/using-graphql-clients) to get started using GraphQL to manage your enterprise accounts. For some example queries, see [An example query using the Enterprise Accounts API](#an-example-query-using-the-enterprise-accounts-api). @@ -206,5 +203,5 @@ For more information about getting started with GraphQL, see [AUTOTITLE](/graphq For more details about the new queries, mutations, and schema defined types available for use with the Enterprise Accounts API, see the sidebar with detailed GraphQL definitions from any [GraphQL reference page](/graphql). -You can access the reference docs from within the GraphQL explorer on GitHub. For more information, see [AUTOTITLE](/graphql/guides/using-the-explorer#accessing-the-sidebar-docs). +You can access the reference docs from within the GraphQL clients. For more information, see [AUTOTITLE](/graphql/guides/using-graphql-clients). For other information, such as authentication and rate limit details, check out the [guides](/graphql/guides). diff --git a/content/graphql/guides/using-graphql-clients.md b/content/graphql/guides/using-graphql-clients.md new file mode 100644 index 000000000000..8cb9ddcad315 --- /dev/null +++ b/content/graphql/guides/using-graphql-clients.md @@ -0,0 +1,74 @@ +--- +title: Using GraphQL Clients +intro: 'You can run queries on real {% data variables.product.prodname_dotcom %} data using various GraphQL clients and libraries.' +redirect_from: + - /v4/guides/using-the-explorer + - /graphql/guides/using-the-explorer +versions: + fpt: '*' + ghec: '*' + ghes: '*' +topics: + - API +--- + +## Using GraphQL client IDEs + +There are many open-source GraphQL client IDEs you can use to access {% data variables.product.company_short %}'s GraphQL API. + +See [AUTOTITLE](/graphql/guides/forming-calls-with-graphql) for extensive information on HTTP methods, authentication, and GraphQL call structure. + +First, choose a client. Common options include GraphiQL, Insomnia, and Altair (desktop/web/extension). You can see the full list of clients in the [GraphQL organization's tool directory](https://graphql.org/community/tools-and-libraries/?tags=services). + +The following generic instructions will work with most GraphQL clients: +1. Point the client at the GraphQL endpoint: `{% data variables.product.graphql_url %}`. +1. Add an `Authorization` header: `Authorization: Bearer TOKEN` (replace `TOKEN` with your {% data variables.product.company_short %} {% data variables.product.pat_generic %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)). +1. Set the request method to `POST` or if it's available, use the client-provided GraphQL mode. +1. Enter your query or mutation in the editor and, if needed, provide variables in the "Variables" panel. + + Example: + + ```graphql + query { + viewer { + login + } + } + ``` + +1. If your client needs a schema for documentation rendering or autocomplete, fetch it via a GraphQL introspection query. Many clients can do this automatically from the "Docs" panel. + + Minimal introspection query: + + ```graphql + query IntrospectionQuery { + __schema { + types { + name + } + } + } + ``` + +1. Run the request and inspect the JSON response. Query from example should return the login associated with the {% data variables.product.company_short %} {% data variables.product.pat_generic %} you authenticated with. + +Use the client UI to explore docs, run queries, and save requests as needed. + +## {% data variables.product.prodname_cli %} + +You can also use the command line with {% data variables.product.prodname_cli %} to run GraphQL queries. + +1. Install and [authenticate with {% data variables.product.prodname_cli %}](https://cli.github.com/manual/gh_auth_login). +1. Run a query against `{% data variables.product.graphql_url %}` using the GraphQL endpoint with the [`gh api` subcommand](https://cli.github.com/manual/gh_api). + +Example: + +```shell +gh api graphql -f query='query { viewer { login } }' +``` + +This should return the login associated with the {% data variables.product.company_short %} {% data variables.product.pat_generic %} you authenticated with. + +## Requesting support + +{% data reusables.support.help_resources %} diff --git a/content/graphql/guides/using-the-explorer.md b/content/graphql/guides/using-the-explorer.md deleted file mode 100644 index 80b1ce9f69c8..000000000000 --- a/content/graphql/guides/using-the-explorer.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Using the Explorer -intro: 'You can run queries on real {% data variables.product.prodname_dotcom %} data using the GraphQL Explorer, an integrated development environment in your browser that includes docs, syntax highlighting, and validation errors.' -redirect_from: - - /v4/guides/using-the-explorer -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -## About the GraphQL Explorer - -{% ifversion ghec %} - -> [!NOTE] -> If your {% data variables.product.prodname_ghe_cloud %} organization uses {% data variables.product.prodname_dotcom %}'s IP allow list, you won't be able to use the GraphQL Explorer. Instead, we recommend using an alternative GraphQL client IDE. - -{% endif %} - -{% ifversion fpt or ghec %} - -[GraphQL Explorer](/graphql/overview/explorer) is an instance of [GraphiQL](https://github.com/graphql/graphiql), which is a "graphical interactive in-browser GraphQL IDE." - -{% else %} - -[GraphiQL](https://github.com/graphql/graphiql), also referred to in this documentation as the GraphQL Explorer, is a "graphical interactive in-browser GraphQL IDE." - -{% endif %} - -## Query autocompletion - -You can use query autocompletion to help you build queries. In the main pane, within the curly brackets of your query, use control+space or shift+space to display the autocomplete menu. - -## Accessing the sidebar docs - -All types in a GraphQL schema include a `description` field compiled into documentation. The collapsible **Docs** pane on the right side of the Explorer page allows you to browse documentation about the type system. The docs are automatically updated and will drop fields that are {% data variables.release-phases.closing_down %}. - -> [!NOTE] -> The **Docs** sidebar contains the same content that is automatically generated from the schema under [AUTOTITLE](/graphql), though it is formatted differently in places. - -## Using the variable pane - -Some example calls include [variables](/graphql/guides/forming-calls-with-graphql#working-with-variables) written like this: - -```graphql -query($number_of_repos:Int!){ - viewer { - name - repositories(last: $number_of_repos) { - nodes { - name - } - } - } -} -variables { - "number_of_repos": 3 -} -``` - -This is the correct format to submit the call using a `POST` request in a `curl` command (as long as you [escape newlines](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql)). - -If you want to run the call in the Explorer, enter the `query` segment in the main pane and the variables in the **Query Variables** pane below it. Omit the word `variables` from the Explorer: - -```graphql -{ - "number_of_repos": 3 -} -``` - -## Using the Altair GraphQL Client IDE - -There are many open source GraphQL client IDEs. For example, you can use Altair to access {% data variables.product.company_short %}'s GraphQL API. To access the GraphQL API with Altair, download and install it from [altair-graphql/altair](https://github.com/altair-graphql/altair). Then, follow the configuration steps below. - -### Configuring Altair - -1. Get an [access token](/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql). -1. Launch Altair. -1. In the left sidebar, below the Altair logo, click **Set Headers**. A new window will open. -1. In the "Header key" field, enter `Authorization`. -1. In the "Header value" field, enter `Bearer TOKEN`, replacing `TOKEN` with your token from the first step. -1. Click **Save** in the bottom right corner of the window to save your authorization header. -1. In the "GraphQL Endpoint" field, enter your GraphQL URL, such as `{% data variables.product.graphql_url %}`. -1. To load the {% data variables.product.company_short %} GraphQL schema, download the [public schema](/graphql/overview/public-schema). -1. In Altair, click on **Docs** on the top right, then the three dots and **Load Schema...** -1. Select the file public schema that you downloaded in an earlier step. - -> [!NOTE] -> For more information about why `POST` is the method, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql). - -You can test your access by querying yourself: - -```graphql -query { - viewer { - login - } -} -``` - -If everything worked correctly, this will display your login. You're all set to start making queries. - -## Requesting support - -{% data reusables.support.help_resources %} - -## Troubleshooting errors - -Because GraphQL is [introspective](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), the Explorer supports: - -* Intelligent typeaheads aware of the current schema -* Validation error previews as you type - -If you enter a query that is not well-formed or does not pass [schema validation](/graphql/guides/introduction-to-graphql#schema), a popup warns you of an error. If you run the query, the error returns in the response pane. - -A GraphQL response contains several keys: a `data` hash and an `errors` array. - -```json -{ - "data": null, - "errors": [ - { - "message": "Objects must have selections (field 'nodes' returns Repository but has no selections)", - "locations": [ - { - "line": 5, - "column": 8 - } - ] - } - ] -} -``` - -It's possible you might run into an unexpected error that is not related to the schema. If this happens, the message will include a reference code you can use when reporting the issue: - -```json -{ - "data": null, - "errors": [ - { - "message": "Something went wrong while executing your query. This is most likely a GitHub bug. Please include \"7571:3FF6:552G94B:69F45B7:5913BBEQ\" when reporting this issue." - } - ] -} -``` - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} recommends checking for errors before using data in a production environment. In GraphQL, failure is not total: portions of GraphQL queries may succeed while others fail. diff --git a/content/graphql/index.md b/content/graphql/index.md index 10d5e0b38b9f..d7f6bef63e09 100644 --- a/content/graphql/index.md +++ b/content/graphql/index.md @@ -8,7 +8,7 @@ featuredLinks: startHere: - /graphql/guides/forming-calls-with-graphql - /graphql/guides/introduction-to-graphql - - /graphql/guides/using-the-explorer + - /graphql/guides/using-graphql-clients popular: - /graphql/overview/explorer - /graphql/overview/public-schema diff --git a/content/graphql/overview/explorer.md b/content/graphql/overview/explorer.md index 48ae0f44dcda..c1795a6ef99d 100644 --- a/content/graphql/overview/explorer.md +++ b/content/graphql/overview/explorer.md @@ -13,7 +13,15 @@ topics: autogenerated: graphql --- -For more information about how to use the explorer, see [AUTOTITLE](/graphql/guides/using-the-explorer). + + + +> [!WARNING] +> The GraphQL Explorer as an embedded tool will be removed from the documentation on November 1, 2025. See our [changelog announcement](https://github.blog/changelog/2025-08-22-graphql-explorer-removal-from-api-documentation-on-november-1-2025). + +For more information about how to explore {% data variables.product.prodname_dotcom %} GraphQL Schema, see [AUTOTITLE](/graphql/guides/using-graphql-clients). + + {% ifversion ghec %} diff --git a/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md b/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md index 7a68421d97a9..10c7cb39df33 100644 --- a/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md +++ b/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md @@ -13,7 +13,7 @@ shortTitle: Sponsors GraphQL API To get started with the GraphQL API, see [AUTOTITLE](/graphql/guides/introduction-to-graphql). -You can find the details about the Sponsors GraphQL API in the reference docs. For more information, see [AUTOTITLE](/graphql/reference). We recommend using the GraphQL explorer to build your GraphQL calls. For more information, see [AUTOTITLE](/graphql/guides/using-the-explorer). +You can find the details about the Sponsors GraphQL API in the reference docs. For more information, see [AUTOTITLE](/graphql/reference). We recommend using the GraphQL clients to build your GraphQL calls. For more information, see [AUTOTITLE](/graphql/guides/using-graphql-clients). ## Known Issues diff --git a/data/reusables/copilot/zero-budget-changes.md b/data/reusables/copilot/zero-budget-changes.md new file mode 100644 index 000000000000..a109262c5fca --- /dev/null +++ b/data/reusables/copilot/zero-budget-changes.md @@ -0,0 +1,3 @@ +Many accounts have a default $0 budget for {% data variables.product.prodname_copilot_short %} premium requests. Premium requests over the allowance are rejected unless this budget is edited or deleted. + +> [!NOTE] Accounts with a **{% data variables.copilot.copilot_business_short %}** or **{% data variables.copilot.copilot_enterprise_short %}** plan that started after August 22, 2025, do **not** have the default $0 budget, and premium requests are uninterrupted by default. You can limit spending on premium requests by creating a budget or disabling the "Premium request paid usage" policy.