Queries
Every GraphQL schema has a root type for both queries and mutations. The query type defines GraphQL operations that retrieve data from the server.
The example data in the variables and responses below are autogenerated values designed to resemble real inputs. They do not represent actual customer data, and in some cases may require additional validation.
account
Type: AccountType
URL: https://api.octopus.energy/v1/graphql/
Get details about an account.
Query Complexity: 2
Possible Errors:
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query accounts with account number
OR Can view detailed usage
Arguments
| Name | Description |
|---|---|
|
Query
query Account($accountNumber: String!) {
account(accountNumber: $accountNumber) {
accountType
activeHardshipAgreements {
...HardshipAgreementTypeFragment
}
activeReferralSchemes {
...ReferralSchemeTypesFragment
}
address {
...RichAddressTypeFragment
}
annualStatements {
...AnnualStatementConnectionTypeConnectionFragment
}
applications {
...AccountApplicationConnectionTypeConnectionFragment
}
assistanceAgreements {
...AssistanceAgreementTypeFragment
}
balance
bill {
...BillInterfaceFragment
}
billingAddress
billingAddressLine1
billingAddressLine2
billingAddressLine3
billingAddressLine4
billingAddressLine5
billingAddressPostcode
billingCountryCode
billingDeliveryPointIdentifier
billingEmail
billingName
billingOptions {
...BillingOptionsTypeFragment
}
billingPostcode
billingSubName
billingTriggerConfiguration {
...BillingTriggerConfigurationFragment
}
bills {
...BillConnectionTypeConnectionFragment
}
brand
business {
...BusinessTypeFragment
}
campaigns {
...AccountCampaignTypeFragment
}
canBeWithdrawn
canChangePayments
canInputMeterReadingsViaIvr
canModifyPayments {
...CanModifyPaymentsTypeFragment
}
canRenewTariff
canRequestRefund
commsDeliveryPreference
complaints {
...ComplaintConnectionTypeConnectionFragment
}
consents {
...ConsentTypeFragment
}
contributionAgreements {
...ContributionAgreementTypeFragment
}
cotReadingWindowDays
createdAt
currentEstimatedSsd
customerAssets {
...CustomerAssetTypeFragment
}
debtCollectionProceedings {
...DebtCollectionProceedingTypeFragment
}
directDebitInstructions {
...DirectDebitInstructionConnectionTypeConnectionFragment
}
documentAccessibility
earliestPossibleSsd
electricityAgreements {
...ElectricityAgreementTypeFragment
}
eligibilityForWarmHomeDiscount {
...WarmHomeDiscountEligibilityFragment
}
events {
...AccountEventConnectionTypeConnectionFragment
}
fileAttachments {
...AccountFileAttachmentFragment
}
gasAgreements {
...GasAgreementTypeFragment
}
greenAccomplishments {
...GreenAccomplishmentsTypeFragment
}
hasActiveCollectionsProceedings
hasActiveDunningProcess
id
isInBlockingMigration
isInHardship
latestPossibleSsd
ledgers {
...LedgerTypeFragment
}
marketSupplyAgreements {
...AgreementConnectionFragment
}
maximumRefund {
...MaximumRefundTypeFragment
}
metadata {
...MetadataFragment
}
notes {
...AccountNoteTypeFragment
}
number
operationsTeam {
...OperationsTeamTypeFragment
}
overdueBalance
paginatedFileAttachments {
...AccountFileAttachmentConnectionTypeConnectionFragment
}
paginatedPaymentForecast {
...PaymentForecastConnectionTypeConnectionFragment
}
paymentAdequacy {
...PaymentAdequacyTypeFragment
}
paymentMethods {
...PaymentInstructionConnectionTypeConnectionFragment
}
paymentPlans {
...PaymentPlanConnectionTypeConnectionFragment
}
payments {
...AccountPaymentConnectionTypeConnectionFragment
}
paymentSchedules {
...PaymentScheduleConnectionTypeConnectionFragment
}
portfolio {
...PortfolioTypeFragment
}
preferredLanguageForComms
projectedBalance
properties {
...PropertyTypeFragment
}
provisionalTransactions {
...ProvisionalTransactionConnectionTypeConnectionFragment
}
recommendedBalanceAdjustment
references {
...AccountReferenceTypeFragment
}
referrals {
...ReferralConnectionTypeConnectionFragment
}
referralsCreated
refundApproval {
...RefundApprovalTypeFragment
}
reminders {
...AccountReminderConnectionTypeConnectionFragment
}
repayments {
...AccountRepaymentConnectionTypeConnectionFragment
}
requestRefundEligibility {
...RequestRefundEligibilityTypeFragment
}
rewards {
...RewardTypeFragment
}
shouldReviewPayments
smets2Interest
smets2RefusalReason
splitBillingAddress
status
trackerTariffDailyPricing {
...TrackerTariffDailyPricingFragment
}
transactions {
...TransactionConnectionTypeConnectionFragment
}
urn
users {
...AccountUserTypeFragment
}
warmHomeDiscount {
...WarmHomeDiscountFragment
}
}
}
Variables
{
"accountNumber": "A-7FEA1111"
}
Response
{
"data": {
"account": {
"accountType": "BUSINESS",
"activeHardshipAgreements": [HardshipAgreementType],
"activeReferralSchemes": ReferralSchemeTypes,
"address": RichAddressType,
"annualStatements": AnnualStatementConnectionTypeConnection,
"applications": AccountApplicationConnectionTypeConnection,
"assistanceAgreements": [AssistanceAgreementType],
"balance": 83,
"bill": BillInterface,
"billingAddress": "green-trial-require-single-part",
"billingAddressLine1": "ever-have-analysis-financial-hospital",
"billingAddressLine2": "impact-student-avoid-real-product",
"billingAddressLine3": "care-condition-story-including-customer",
"billingAddressLine4": "dog-at-share-those-carry",
"billingAddressLine5": "catch-word-be-loss-direction",
"billingAddressPostcode": "financial-majority-light-teacher-simply",
"billingCountryCode": "could-close-budget-green-painting",
"billingDeliveryPointIdentifier": "57391372",
"billingEmail": "option-national-its-wrong-movie",
"billingName": "fast-member-course-trial-career",
"billingOptions": BillingOptionsType,
"billingPostcode": "baby-card-attorney-east-clear",
"billingSubName": "range-official-born-movie-produce",
"billingTriggerConfiguration": BillingTriggerConfiguration,
"bills": BillConnectionTypeConnection,
"brand": "education-author-event-live-whole",
"business": BusinessType,
"campaigns": [AccountCampaignType],
"canBeWithdrawn": true,
"canChangePayments": true,
"canInputMeterReadingsViaIvr": true,
"canModifyPayments": CanModifyPaymentsType,
"canRenewTariff": true,
"canRequestRefund": true,
"commsDeliveryPreference": "EMAIL",
"complaints": ComplaintConnectionTypeConnection,
"consents": [ConsentType],
"contributionAgreements": [ContributionAgreementType],
"cotReadingWindowDays": 79,
"createdAt": "1999-01-15T05:44:24.769894+00:00",
"currentEstimatedSsd": "2024-05-06",
"customerAssets": [CustomerAssetType],
"debtCollectionProceedings": [DebtCollectionProceedingType],
"directDebitInstructions": DirectDebitInstructionConnectionTypeConnection,
"documentAccessibility": "LARGE_PRINT",
"earliestPossibleSsd": "1984-11-04",
"electricityAgreements": [ElectricityAgreementType],
"eligibilityForWarmHomeDiscount": WarmHomeDiscountEligibility,
"events": AccountEventConnectionTypeConnection,
"fileAttachments": [AccountFileAttachment],
"gasAgreements": [GasAgreementType],
"greenAccomplishments": GreenAccomplishmentsType,
"hasActiveCollectionsProceedings": true,
"hasActiveDunningProcess": true,
"id": "83859739",
"isInBlockingMigration": true,
"isInHardship": true,
"latestPossibleSsd": "1981-06-12",
"ledgers": [LedgerType],
"marketSupplyAgreements": AgreementConnection,
"maximumRefund": MaximumRefundType,
"metadata": [Metadata],
"notes": [AccountNoteType],
"number": "court-force-land-even-evidence",
"operationsTeam": OperationsTeamType,
"overdueBalance": 2,
"paginatedFileAttachments": AccountFileAttachmentConnectionTypeConnection,
"paginatedPaymentForecast": PaymentForecastConnectionTypeConnection,
"paymentAdequacy": PaymentAdequacyType,
"paymentMethods": PaymentInstructionConnectionTypeConnection,
"paymentPlans": PaymentPlanConnectionTypeConnection,
"payments": AccountPaymentConnectionTypeConnection,
"paymentSchedules": PaymentScheduleConnectionTypeConnection,
"portfolio": PortfolioType,
"preferredLanguageForComms": "seven-building-agree-tell-detail",
"projectedBalance": 4,
"properties": [PropertyType],
"provisionalTransactions": ProvisionalTransactionConnectionTypeConnection,
"recommendedBalanceAdjustment": 2,
"references": [AccountReferenceType],
"referrals": ReferralConnectionTypeConnection,
"referralsCreated": 81,
"refundApproval": RefundApprovalType,
"reminders": AccountReminderConnectionTypeConnection,
"repayments": AccountRepaymentConnectionTypeConnection,
"requestRefundEligibility": RequestRefundEligibilityType,
"rewards": [RewardType],
"shouldReviewPayments": true,
"smets2Interest": "PRIORITY",
"smets2RefusalReason": "SMETS2_INTEREST_REASON_DO_NOT_OWN_HOME",
"splitBillingAddress": "affect-still-if-about-not",
"status": "PENDING",
"trackerTariffDailyPricing": TrackerTariffDailyPricing,
"transactions": TransactionConnectionTypeConnection,
"urn": "movie-out-various-happen-camera",
"users": [AccountUserType],
"warmHomeDiscount": WarmHomeDiscount
}
}
}
accountChargeReasons
Type: [ChargeReasonType]
URL: https://api.octopus.energy/v1/graphql/
Available reasons for use in account charge mutations.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can add charges to accounts
Query
query AccountChargeReasons {
accountChargeReasons {
code
display
group
isDeprecated
isHidden
isTaxExempt
}
}
Response
{
"data": {
"accountChargeReasons": [
{
"code": "need-tell-run-party-school",
"display": "main-structure-table-cause-window",
"group": "happy-site-consumer-notice-work",
"isDeprecated": true,
"isHidden": true,
"isTaxExempt": true
}
]
}
}
accountContract
Type: Contract
URL: https://api.octopus.energy/v1/graphql/
Get details about an account contract.
Query Complexity: 1
Possible Errors:
- KT-CT-10003: Contract not found.
- KT-CT-10005: Missing required parameter: either identifier or accountNumber must be provided.
- KT-CT-10006: Account not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query contracts
Arguments
| Name | Description |
|---|---|
|
The account number to find the contract for. |
|
The identifier of the contract. |
|
The version of the contract. |
Query
query AccountContract(
$accountNumber: String,
$identifier: String,
$version: Int
) {
accountContract(
accountNumber: $accountNumber,
identifier: $identifier,
version: $version
) {
cancelledAt
identifier
lifecycle {
...ContractVersionFragment
}
notes {
...ContractNoteTypeFragment
}
party {
... on AccountType {
...AccountTypeFragment
}
... on BusinessType {
...BusinessTypeFragment
}
}
rescindedAt
signedAt
status
subject {
...AccountTypeFragment
}
terms {
...TermInterfaceFragment
}
title
validFrom
validTo
}
}
Variables
{
"accountNumber": "A-BEFCC127",
"identifier": "29677624",
"version": 4
}
Response
{
"data": {
"accountContract": {
"cancelledAt": "1997-05-19T10:19:33.301322+00:00",
"identifier": "43447883",
"lifecycle": ContractVersion,
"notes": [ContractNoteType],
"party": AccountType,
"rescindedAt": "2017-03-31T05:50:11.192307+00:00",
"signedAt": "2005-07-29T03:09:47.470145+00:00",
"status": "REVOKED",
"subject": [AccountType],
"terms": TermInterface,
"title": "total-suggest-site-fish-fish",
"validFrom": "1976-07-26T18:42:04.916695+00:00",
"validTo": "2012-10-09T00:15:26.661161+00:00"
}
}
}
accountCreditReasons
Type: [CreditReasonType]
URL: https://api.octopus.energy/v1/graphql/
Available reasons for use in account credit mutations.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can add credits to accounts
Query
query AccountCreditReasons {
accountCreditReasons {
code
display
group
isDeprecated
isHidden
isTaxExempt
}
}
Response
{
"data": {
"accountCreditReasons": [
{
"code": "notice-shake-amount-sell-happen",
"display": "still-I-member-language-since",
"group": "natural-husband-low-foot-single",
"isDeprecated": true,
"isHidden": true,
"isTaxExempt": true
}
]
}
}
accountDebtPosition
Type: AccountDebtPositionType
URL: https://api.octopus.energy/v1/graphql/
The delinquent debt position for an account and its ledgers.
Query Complexity: 2
Possible Errors:
- KT-CT-11613: Delinquent debt tracking is not configured for this client.
- KT-CT-4178: No account found with given account number.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query delinquent debt positions for ledgers
Arguments
| Name | Description |
|---|---|
|
The account number to retrieve debt position for. |
|
The date to retrieve the debt position for. If not provided, defaults to today. Allows querying historical debt positions. If a future date is provided, it is clamped to today. |
Query
query AccountDebtPosition(
$accountNumber: String!,
$asOn: Date
) {
accountDebtPosition(
accountNumber: $accountNumber,
asOn: $asOn
) {
accountNumber
ledgerDebtPositions {
...LedgerDebtPositionTypeFragment
}
}
}
Variables
{
"accountNumber": "A-5E390501",
"asOn": "1999-01-21"
}
Response
{
"data": {
"accountDebtPosition": {
"accountNumber": "A-AD562E60",
"ledgerDebtPositions": [LedgerDebtPositionType]
}
}
}
accountIoEligibility
Type: AccountIoEligibility
URL: https://api.octopus.energy/v1/graphql/
Determines whether an account is eligible to register devices with SmartFlex.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can view smartflex data
Arguments
| Name | Description |
|---|---|
|
Account number. |
|
|
Query
query AccountIoEligibility(
$accountNumber: String!,
$propertyId: Int
) {
accountIoEligibility(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
isEligibleForIo
}
}
Variables
{
"accountNumber": "A-869D15F1",
"propertyId": 32797327
}
Response
{
"data": {
"accountIoEligibility": {
"isEligibleForIo": true
}
}
}
accountPaymentById
Type: OEGBAccountPaymentType
URL: https://api.octopus.energy/v1/graphql/
Query a payment for an account by id.
Query Complexity: 1
Possible Errors:
- KT-CT-3924: Unauthorized.
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
|
The id of the payment. |
Query
query AccountPaymentById(
$accountNumber: String!,
$paymentId: ID!
) {
accountPaymentById(
accountNumber: $accountNumber,
paymentId: $paymentId
) {
amount
id
isAmendable
isCancelled
paymentDate
}
}
Variables
{
"accountNumber": "A-F16E1E02",
"paymentId": "96127165"
}
Response
{
"data": {
"accountPaymentById": {
"amount": 85,
"id": "80425664",
"isAmendable": true,
"isCancelled": true,
"paymentDate": "2022-01-03"
}
}
}
accountReference
Type: [AccountReferenceType]
URL: https://api.octopus.energy/v1/graphql/
List of matching account references.
Query Complexity: 1
Possible Errors:
- KT-CT-8310: Invalid data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query account reference
Arguments
| Name | Description |
|---|---|
|
Filter account references by this value. |
Query
query AccountReference($value: String) {
accountReference(value: $value) {
account {
...AccountTypeFragment
}
createdAt
namespace
updatedAt
value
}
}
Variables
{
"value": "billion-realize-keep-score-letter"
}
Response
{
"data": {
"accountReference": [
{
"account": AccountType,
"createdAt": "2025-04-07T00:33:12.246109+00:00",
"namespace": "factor-protect-score-daughter-sure",
"updatedAt": "1998-09-26T05:56:56.207482+00:00",
"value": "pass-parent-leg-here-campaign"
}
]
}
}
accounts
Type: [AccountType]
URL: https://api.octopus.energy/v1/graphql/
Get details about multiple accounts.
Query Complexity: 1
Possible Errors:
- KT-CT-4184: Exactly one of phoneNumber or portfolioNumber must be provided.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can search for accounts
Arguments
| Name | Description |
|---|---|
|
A phone number to find accounts associated with. |
|
A portfolio number to find accounts associated with. |
Query
query Accounts(
$phoneNumber: String,
$portfolioNumber: String
) {
accounts(
phoneNumber: $phoneNumber,
portfolioNumber: $portfolioNumber
) {
accountType
activeHardshipAgreements {
...HardshipAgreementTypeFragment
}
activeReferralSchemes {
...ReferralSchemeTypesFragment
}
address {
...RichAddressTypeFragment
}
annualStatements {
...AnnualStatementConnectionTypeConnectionFragment
}
applications {
...AccountApplicationConnectionTypeConnectionFragment
}
assistanceAgreements {
...AssistanceAgreementTypeFragment
}
balance
bill {
...BillInterfaceFragment
}
billingAddress
billingAddressLine1
billingAddressLine2
billingAddressLine3
billingAddressLine4
billingAddressLine5
billingAddressPostcode
billingCountryCode
billingDeliveryPointIdentifier
billingEmail
billingName
billingOptions {
...BillingOptionsTypeFragment
}
billingPostcode
billingSubName
billingTriggerConfiguration {
...BillingTriggerConfigurationFragment
}
bills {
...BillConnectionTypeConnectionFragment
}
brand
business {
...BusinessTypeFragment
}
campaigns {
...AccountCampaignTypeFragment
}
canBeWithdrawn
canChangePayments
canInputMeterReadingsViaIvr
canModifyPayments {
...CanModifyPaymentsTypeFragment
}
canRenewTariff
canRequestRefund
commsDeliveryPreference
complaints {
...ComplaintConnectionTypeConnectionFragment
}
consents {
...ConsentTypeFragment
}
contributionAgreements {
...ContributionAgreementTypeFragment
}
cotReadingWindowDays
createdAt
currentEstimatedSsd
customerAssets {
...CustomerAssetTypeFragment
}
debtCollectionProceedings {
...DebtCollectionProceedingTypeFragment
}
directDebitInstructions {
...DirectDebitInstructionConnectionTypeConnectionFragment
}
documentAccessibility
earliestPossibleSsd
electricityAgreements {
...ElectricityAgreementTypeFragment
}
eligibilityForWarmHomeDiscount {
...WarmHomeDiscountEligibilityFragment
}
events {
...AccountEventConnectionTypeConnectionFragment
}
fileAttachments {
...AccountFileAttachmentFragment
}
gasAgreements {
...GasAgreementTypeFragment
}
greenAccomplishments {
...GreenAccomplishmentsTypeFragment
}
hasActiveCollectionsProceedings
hasActiveDunningProcess
id
isInBlockingMigration
isInHardship
latestPossibleSsd
ledgers {
...LedgerTypeFragment
}
marketSupplyAgreements {
...AgreementConnectionFragment
}
maximumRefund {
...MaximumRefundTypeFragment
}
metadata {
...MetadataFragment
}
notes {
...AccountNoteTypeFragment
}
number
operationsTeam {
...OperationsTeamTypeFragment
}
overdueBalance
paginatedFileAttachments {
...AccountFileAttachmentConnectionTypeConnectionFragment
}
paginatedPaymentForecast {
...PaymentForecastConnectionTypeConnectionFragment
}
paymentAdequacy {
...PaymentAdequacyTypeFragment
}
paymentMethods {
...PaymentInstructionConnectionTypeConnectionFragment
}
paymentPlans {
...PaymentPlanConnectionTypeConnectionFragment
}
payments {
...AccountPaymentConnectionTypeConnectionFragment
}
paymentSchedules {
...PaymentScheduleConnectionTypeConnectionFragment
}
portfolio {
...PortfolioTypeFragment
}
preferredLanguageForComms
projectedBalance
properties {
...PropertyTypeFragment
}
provisionalTransactions {
...ProvisionalTransactionConnectionTypeConnectionFragment
}
recommendedBalanceAdjustment
references {
...AccountReferenceTypeFragment
}
referrals {
...ReferralConnectionTypeConnectionFragment
}
referralsCreated
refundApproval {
...RefundApprovalTypeFragment
}
reminders {
...AccountReminderConnectionTypeConnectionFragment
}
repayments {
...AccountRepaymentConnectionTypeConnectionFragment
}
requestRefundEligibility {
...RequestRefundEligibilityTypeFragment
}
rewards {
...RewardTypeFragment
}
shouldReviewPayments
smets2Interest
smets2RefusalReason
splitBillingAddress
status
trackerTariffDailyPricing {
...TrackerTariffDailyPricingFragment
}
transactions {
...TransactionConnectionTypeConnectionFragment
}
urn
users {
...AccountUserTypeFragment
}
warmHomeDiscount {
...WarmHomeDiscountFragment
}
}
}
Variables
{
"phoneNumber": "sit-for-read-second-film",
"portfolioNumber": "P-AE7E8876"
}
Response
{
"data": {
"accounts": [
{
"accountType": "BUSINESS",
"activeHardshipAgreements": [HardshipAgreementType],
"activeReferralSchemes": ReferralSchemeTypes,
"address": RichAddressType,
"annualStatements": AnnualStatementConnectionTypeConnection,
"applications": AccountApplicationConnectionTypeConnection,
"assistanceAgreements": [AssistanceAgreementType],
"balance": 14,
"bill": BillInterface,
"billingAddress": "town-ask-new-board-newspaper",
"billingAddressLine1": "major-be-about-necessary-ever",
"billingAddressLine2": "member-especially-maybe-this-game",
"billingAddressLine3": "central-dark-bad-here-view",
"billingAddressLine4": "sit-enough-people-east-owner",
"billingAddressLine5": "three-outside-ask-bag-involve",
"billingAddressPostcode": "write-together-keep-charge-game",
"billingCountryCode": "these-strong-development-station-rather",
"billingDeliveryPointIdentifier": "73565379",
"billingEmail": "something-bring-road-weight-property",
"billingName": "shake-suggest-size-add-week",
"billingOptions": BillingOptionsType,
"billingPostcode": "film-strong-sometimes-simply-them",
"billingSubName": "a-green-indeed-vote-successful",
"billingTriggerConfiguration": BillingTriggerConfiguration,
"bills": BillConnectionTypeConnection,
"brand": "city-manager-huge-catch-bed",
"business": BusinessType,
"campaigns": [AccountCampaignType],
"canBeWithdrawn": true,
"canChangePayments": true,
"canInputMeterReadingsViaIvr": true,
"canModifyPayments": CanModifyPaymentsType,
"canRenewTariff": true,
"canRequestRefund": true,
"commsDeliveryPreference": "EMAIL",
"complaints": ComplaintConnectionTypeConnection,
"consents": [ConsentType],
"contributionAgreements": [ContributionAgreementType],
"cotReadingWindowDays": 46,
"createdAt": "2018-06-22T07:45:19.492989+00:00",
"currentEstimatedSsd": "1972-04-27",
"customerAssets": [CustomerAssetType],
"debtCollectionProceedings": [DebtCollectionProceedingType],
"directDebitInstructions": DirectDebitInstructionConnectionTypeConnection,
"documentAccessibility": "LARGE_PRINT",
"earliestPossibleSsd": "1982-05-04",
"electricityAgreements": [ElectricityAgreementType],
"eligibilityForWarmHomeDiscount": WarmHomeDiscountEligibility,
"events": AccountEventConnectionTypeConnection,
"fileAttachments": [AccountFileAttachment],
"gasAgreements": [GasAgreementType],
"greenAccomplishments": GreenAccomplishmentsType,
"hasActiveCollectionsProceedings": true,
"hasActiveDunningProcess": true,
"id": "98360764",
"isInBlockingMigration": true,
"isInHardship": true,
"latestPossibleSsd": "1970-06-15",
"ledgers": [LedgerType],
"marketSupplyAgreements": AgreementConnection,
"maximumRefund": MaximumRefundType,
"metadata": [Metadata],
"notes": [AccountNoteType],
"number": "up-film-fly-fast-sort",
"operationsTeam": OperationsTeamType,
"overdueBalance": 61,
"paginatedFileAttachments": AccountFileAttachmentConnectionTypeConnection,
"paginatedPaymentForecast": PaymentForecastConnectionTypeConnection,
"paymentAdequacy": PaymentAdequacyType,
"paymentMethods": PaymentInstructionConnectionTypeConnection,
"paymentPlans": PaymentPlanConnectionTypeConnection,
"payments": AccountPaymentConnectionTypeConnection,
"paymentSchedules": PaymentScheduleConnectionTypeConnection,
"portfolio": PortfolioType,
"preferredLanguageForComms": "end-watch-city-house-total",
"projectedBalance": 47,
"properties": [PropertyType],
"provisionalTransactions": ProvisionalTransactionConnectionTypeConnection,
"recommendedBalanceAdjustment": 59,
"references": [AccountReferenceType],
"referrals": ReferralConnectionTypeConnection,
"referralsCreated": 37,
"refundApproval": RefundApprovalType,
"reminders": AccountReminderConnectionTypeConnection,
"repayments": AccountRepaymentConnectionTypeConnection,
"requestRefundEligibility": RequestRefundEligibilityType,
"rewards": [RewardType],
"shouldReviewPayments": true,
"smets2Interest": "PRIORITY",
"smets2RefusalReason": "SMETS2_INTEREST_REASON_DO_NOT_OWN_HOME",
"splitBillingAddress": "responsibility-lot-learn-notice-arm",
"status": "PENDING",
"trackerTariffDailyPricing": TrackerTariffDailyPricing,
"transactions": TransactionConnectionTypeConnection,
"urn": "policy-difficult-purpose-nice-bed",
"users": [AccountUserType],
"warmHomeDiscount": WarmHomeDiscount
}
]
}
}
accountsSearch
Type: [AccountSearchItemType]
URL: https://api.octopus.energy/v1/graphql/
Search for account that are already in Kraken and match the search terms.
Query Complexity: 1
Possible Errors:
- KT-CT-4183: One of more search terms failed validations.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can search for accounts
Arguments
| Name | Description |
|---|---|
|
The maximum number of results to return. |
|
Search operators. |
Query
query AccountsSearch(
$maxResults: Int,
$searchTerms: AccountSearchInputType
) {
accountsSearch(
maxResults: $maxResults,
searchTerms: $searchTerms
) {
account {
...AccountTypeFragment
}
score
}
}
Variables
{
"maxResults": 91,
"searchTerms": AccountSearchInputType
}
Response
{
"data": {
"accountsSearch": [
{
"account": AccountType,
"score": "1.0"
}
]
}
}
accountStatusSearchByNumber
Type: AccountWithStatusInfoType
URL: https://api.octopus.energy/v1/graphql/
Get account status information given its number.
Query Complexity: 1
Possible Errors:
- KT-CT-7523: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number to search for. |
Query
query AccountStatusSearchByNumber($accountNumber: String!) {
accountStatusSearchByNumber(accountNumber: $accountNumber) {
activePaymentMethod
balance
canModifyPayments {
...CanModifyPaymentsTypeFragment
}
marketSupplyAgreements {
...AgreementConnectionFragment
}
number
properties {
...PropertyTypeFragment
}
status
}
}
Variables
{
"accountNumber": "A-A4F9A2E3"
}
Response
{
"data": {
"accountStatusSearchByNumber": {
"activePaymentMethod": "play-blue-family-itself-agent",
"balance": 15,
"canModifyPayments": CanModifyPaymentsType,
"marketSupplyAgreements": AgreementConnection,
"number": "painting-kind-despite-the-fish",
"properties": [PropertyType],
"status": "PENDING"
}
}
}
accountUser
Type: AccountUserType
URL: https://api.octopus.energy/v1/graphql/
Retrieve an account user.
Query Complexity: 1
Possible Errors:
- KT-CT-5415: Account user not found.
- KT-CT-5418: Account user not found.
- KT-CT-5421: Account user not found.
- KT-CT-5423: Account user not found.
- KT-CT-5424: Invalid data.
- KT-CT-5425: Account user not found.
- KT-CT-5427: Account user not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query account user
Arguments
| Name | Description |
|---|---|
|
Account user detail namespace/value pair which uniquely identifies a user. |
|
Email associated with an account user. |
|
External ID associated with an account user. |
|
Kraken number associated with an account user. |
Query
query AccountUser(
$detail: AccountUserDetailInput,
$email: String,
$externalId: ID,
$number: ID
) {
accountUser(
detail: $detail,
email: $email,
externalId: $externalId,
number: $number
) {
accounts {
...AccountInterfaceFragment
}
accountUserRoles {
...AccountUserRoleTypeFragment
}
address {
...RichAddressTypeFragment
}
alternativePhoneNumbers
businesses {
...BusinessConnectionTypeConnectionFragment
}
consents {
...ConsentTypeFragment
}
createdAt
dateOfBirth
details {
...AccountUserDetailTypeFragment
}
email
familyName
fullName
givenName
hasFamilyIssues
holdMusicChoices {
...TrackOptionTypeFragment
}
id
isActive
isDeceased
isInHardship
isOptedInToWof
label
landline
liveSecretKey
mobile
number
paymentMethods {
...PaymentInstructionConnectionTypeConnectionFragment
}
permissions {
...AccountUserPermissionFragment
}
portfolioIds
portfolios {
...PortfolioConnectionTypeConnectionFragment
}
portfolioUserRoles {
...PortfolioUserRoleTypeFragment
}
preferences {
...AccountUserCommsPreferencesFragment
}
preferredName
pronouns
specialCircumstances {
...SpecialCircumstancesTypeFragment
}
title
}
}
Variables
{
"detail": AccountUserDetailInput,
"email": "commercial-price-body-rise-up",
"externalId": "35428315",
"number": "25113850"
}
Response
{
"data": {
"accountUser": {
"accounts": AccountInterface,
"accountUserRoles": [AccountUserRoleType],
"address": RichAddressType,
"alternativePhoneNumbers": "leave-quickly-there-federal-stuff",
"businesses": BusinessConnectionTypeConnection,
"consents": [ConsentType],
"createdAt": "2018-12-12T02:50:56.623561+00:00",
"dateOfBirth": "1996-09-11",
"details": [AccountUserDetailType],
"email": "measure-who-down-attack-different",
"familyName": "Conrad",
"fullName": "still-themselves-us-report-raise",
"givenName": "Thomas",
"hasFamilyIssues": true,
"holdMusicChoices": [TrackOptionType],
"id": "78950005",
"isActive": true,
"isDeceased": true,
"isInHardship": true,
"isOptedInToWof": true,
"label": "cold-air-difference-beyond-attack",
"landline": "sort-receive-speak-land-weight",
"liveSecretKey": "card-raise-film-popular-single",
"mobile": "physical-often-already-thousand-place",
"number": "resource-speech-cold-specific-film",
"paymentMethods": PaymentInstructionConnectionTypeConnection,
"permissions": [AccountUserPermission],
"portfolioIds": "78309702",
"portfolios": PortfolioConnectionTypeConnection,
"portfolioUserRoles": [PortfolioUserRoleType],
"preferences": AccountUserCommsPreferences,
"preferredName": "war-activity-school-response-book",
"pronouns": "station-your-blue-wrong-subject",
"specialCircumstances": SpecialCircumstancesType,
"title": "suggest-head-stage-not-knowledge"
}
}
}
accountUserSearch
Type: AccountUserType!
URL: https://api.octopus.energy/v1/graphql/
Account User Search
This query returns an AccountUserType attempting to match against the request.
We attempt to find a user with a close or exact match to the fields provided
with a confidence score >= that of the threshold argument, if threshold
isn't provided we use a internal base threshold of 1.0
tweak this parameter if you are not getting results as you'd expect.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query account user
Arguments
| Name | Description |
|---|---|
|
Query
query AccountUserSearch($input: AccountUserSearchInputType) {
accountUserSearch(input: $input) {
accounts {
...AccountInterfaceFragment
}
accountUserRoles {
...AccountUserRoleTypeFragment
}
address {
...RichAddressTypeFragment
}
alternativePhoneNumbers
businesses {
...BusinessConnectionTypeConnectionFragment
}
consents {
...ConsentTypeFragment
}
createdAt
dateOfBirth
details {
...AccountUserDetailTypeFragment
}
email
familyName
fullName
givenName
hasFamilyIssues
holdMusicChoices {
...TrackOptionTypeFragment
}
id
isActive
isDeceased
isInHardship
isOptedInToWof
label
landline
liveSecretKey
mobile
number
paymentMethods {
...PaymentInstructionConnectionTypeConnectionFragment
}
permissions {
...AccountUserPermissionFragment
}
portfolioIds
portfolios {
...PortfolioConnectionTypeConnectionFragment
}
portfolioUserRoles {
...PortfolioUserRoleTypeFragment
}
preferences {
...AccountUserCommsPreferencesFragment
}
preferredName
pronouns
specialCircumstances {
...SpecialCircumstancesTypeFragment
}
title
}
}
Variables
{
"input": AccountUserSearchInputType
}
Response
{
"data": {
"accountUserSearch": {
"accounts": AccountInterface,
"accountUserRoles": [AccountUserRoleType],
"address": RichAddressType,
"alternativePhoneNumbers": "early-as-another-economy-reach",
"businesses": BusinessConnectionTypeConnection,
"consents": [ConsentType],
"createdAt": "1988-09-13T18:31:28.662318+00:00",
"dateOfBirth": "1982-11-25",
"details": [AccountUserDetailType],
"email": "imagine-city-management-Mrs-stand",
"familyName": "Estrada",
"fullName": "face-determine-father-discussion-six",
"givenName": "Derek",
"hasFamilyIssues": true,
"holdMusicChoices": [TrackOptionType],
"id": "21350705",
"isActive": true,
"isDeceased": true,
"isInHardship": true,
"isOptedInToWof": true,
"label": "name-bag-very-fire-between",
"landline": "hard-fill-play-near-either",
"liveSecretKey": "commercial-Congress-around-agreement-all",
"mobile": "term-tax-safe-partner-nature",
"number": "in-marriage-benefit-benefit-cause",
"paymentMethods": PaymentInstructionConnectionTypeConnection,
"permissions": [AccountUserPermission],
"portfolioIds": "52081998",
"portfolios": PortfolioConnectionTypeConnection,
"portfolioUserRoles": [PortfolioUserRoleType],
"preferences": AccountUserCommsPreferences,
"preferredName": "billion-to-between-perform-last",
"pronouns": "large-upon-walk-spring-country",
"specialCircumstances": SpecialCircumstancesType,
"title": "father-operation-party-Democrat-whether"
}
}
}
activeAffiliateReferralScheme
Type: ReferralSchemeType
URL: https://api.octopus.energy/v1/graphql/
Return the current active referral reward scheme of a given affiliate organisation, if any exists.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can create affiliate links
OR Can query affiliate links
OR Can update affiliate links
Arguments
| Name | Description |
|---|---|
|
The account type for which to get the referral scheme. |
|
The affiliate link subdomain. |
Query
query ActiveAffiliateReferralScheme(
$accountType: ReferralSchemeAccountTypeOptions,
$subdomain: String!
) {
activeAffiliateReferralScheme(
accountType: $accountType,
subdomain: $subdomain
) {
canBeReferred
code
combinedRewardAmount
isUsageAtCapacity
loyaltyPointsBonus
maxRecurrence
referralDisplayUrl
referralUrl
referredRewardAmount
referrerGivenName
referrerRewardAmount
schemeType
}
}
Variables
{
"accountType": "DOMESTIC",
"subdomain": "same-effect-design-rule-in"
}
Response
{
"data": {
"activeAffiliateReferralScheme": {
"canBeReferred": true,
"code": "sell-consider-generation-anything-her",
"combinedRewardAmount": 42,
"isUsageAtCapacity": true,
"loyaltyPointsBonus": 33,
"maxRecurrence": 25,
"referralDisplayUrl": "clear-deep-later-catch-through",
"referralUrl": "follow-step-walk-media-nothing",
"referredRewardAmount": 29,
"referrerGivenName": "Regina",
"referrerRewardAmount": 92,
"schemeType": "blood-ten-still-walk-dinner"
}
}
}
activeCampaignOffers
Type: [CampaignType]
URL: https://api.octopus.energy/v1/graphql/
All active campaigns with offers for the given account.
Query Complexity: 1
Possible Errors:
- KT-CT-7423: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Query
query ActiveCampaignOffers($accountNumber: String!) {
activeCampaignOffers(accountNumber: $accountNumber) {
expiryDate
name
slug
}
}
Variables
{
"accountNumber": "A-D1990F2E"
}
Response
{
"data": {
"activeCampaignOffers": [
{
"expiryDate": "1997-04-10",
"name": "nor-beautiful-hospital-economic-toward",
"slug": "PM-population-couple-grow-avoid"
}
]
}
}
activeDomesticSignupRewardScheme
Type: ReferralSchemeType
URL: https://api.octopus.energy/v1/graphql/
Return the current active signup referral reward scheme with the given code, if any exists.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query ActiveDomesticSignupRewardScheme {
activeDomesticSignupRewardScheme {
canBeReferred
code
combinedRewardAmount
isUsageAtCapacity
loyaltyPointsBonus
maxRecurrence
referralDisplayUrl
referralUrl
referredRewardAmount
referrerGivenName
referrerRewardAmount
schemeType
}
}
Response
{
"data": {
"activeDomesticSignupRewardScheme": {
"canBeReferred": true,
"code": "into-let-others-evening-both",
"combinedRewardAmount": 22,
"isUsageAtCapacity": true,
"loyaltyPointsBonus": 24,
"maxRecurrence": 39,
"referralDisplayUrl": "administration-use-begin-appear-employee",
"referralUrl": "add-weight-according-discuss-hair",
"referredRewardAmount": 17,
"referrerGivenName": "Tyrone",
"referrerRewardAmount": 63,
"schemeType": "new-wrong-black-nor-road"
}
}
}
activeSalesChannels
Type: [SalesChannelType]
URL: https://api.octopus.energy/v1/graphql/
A list of active sales channels.
Query Complexity: 4
Possible Errors:
- KT-CT-12702: Invalid datetime range.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query sales channels
Arguments
| Name | Description |
|---|---|
|
The datetime from which to filter active sales channels. |
|
The datetime up to which to filter active sales channels. |
Query
query ActiveSalesChannels(
$activeFrom: DateTime,
$activeTo: DateTime
) {
activeSalesChannels(
activeFrom: $activeFrom,
activeTo: $activeTo
) {
code
description
hierarchicalName
name
}
}
Variables
{
"activeFrom": "1976-06-03T09:51:05.199893+00:00",
"activeTo": "2020-07-23T22:40:41.569341+00:00"
}
Response
{
"data": {
"activeSalesChannels": [
{
"code": "tend-customer-maybe-kid-fear",
"description": "hit-model-hot-magazine-president",
"hierarchicalName": "mention-future-sister-no-behind",
"name": "artist-operation-sea-admit-hour"
}
]
}
}
addresses
Type: AddressConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 6
Possible Errors:
- KT-GB-6610: We're sorry but we can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6611: We couldn't find a match for this postcode. Please verify it and try again.
- KT-GB-6620: Invalid data.
- KT-GB-6621: Invalid data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Query
query Addresses(
$after: String,
$before: String,
$dataSource: DataSource,
$first: Int,
$last: Int,
$postcode: String!,
$searchDomesticOnly: Boolean,
$useDes: Boolean
) {
addresses(
after: $after,
before: $before,
dataSource: $dataSource,
first: $first,
last: $last,
postcode: $postcode,
searchDomesticOnly: $searchDomesticOnly,
useDes: $useDes
) {
edgeCount
edges {
...AddressConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"dataSource": "CACHE",
"first": 10,
"last": 10,
"postcode": "wife-south-like-particularly-character",
"searchDomesticOnly": true,
"useDes": true
}
Response
{
"data": {
"addresses": {
"edgeCount": 83,
"edges": [AddressConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 45
}
}
}
addressFields
Type: AddressFieldDescriptorType
URL: https://api.octopus.energy/v1/graphql/
Get the address field descriptor for a given identifier. The identifier can be an ISO 3166-1 alpha-2 country code (e.g. 'AU', 'GB') or a custom descriptor key configured for the deployment. Returns null if the identifier is not recognised.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['10/s'] |
Arguments
| Name | Description |
|---|---|
|
Address field descriptor identifier. Typically an ISO 3166-1 alpha-2 country code, but may also be a custom descriptor key. |
Query
query AddressFields($addressFieldDescriptorId: String!) {
addressFields(addressFieldDescriptorId: $addressFieldDescriptorId) {
fieldGroups {
...AddressFieldGroupTypeFragment
}
}
}
Variables
{
"addressFieldDescriptorId": "97551423"
}
Response
{
"data": {
"addressFields": {
"fieldGroups": [AddressFieldGroupType]
}
}
}
addressMeterpoints
Type: AddressMeterPointsType
URL: https://api.octopus.energy/v1/graphql/
Search for all energised meterpoint's belonging to the given UPRN using ECOES & Xoserve APIs.
Query Complexity: 6
Possible Errors:
- KT-GB-6620: Invalid data.
- KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6631: Invalid data.
- KT-GB-6632: UPRN not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The postcode of the property to search for meterpoints. |
|
The UPRN of the property to search for meterpoints. |
Query
query AddressMeterpoints(
$postcode: String!,
$uprn: String!
) {
addressMeterpoints(
postcode: $postcode,
uprn: $uprn
) {
electricityMeterPoints {
...ElectricMeterTechnicalDetailsFragment
}
electricityNetworkRates {
...ElectricityNetworkRatesFragment
}
gasMeterPoints {
...GasMeterTechnicalDetailsFragment
}
}
}
Variables
{
"postcode": "like-street-wide-painting-teacher",
"uprn": "outside-let-than-page-now"
}
Response
{
"data": {
"addressMeterpoints": {
"electricityMeterPoints": [ElectricMeterTechnicalDetails],
"electricityNetworkRates": [ElectricityNetworkRates],
"gasMeterPoints": [GasMeterTechnicalDetails]
}
}
}
addressUprns
Type: AddressUPRNTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Search for addresses belonging to the given postcode using ECOES & Xoserve APIs, with the results grouped by UPRN.
Query Complexity: 6
Possible Errors:
- KT-GB-6611: We couldn't find a match for this postcode. Please verify it and try again.
- KT-GB-6620: Invalid data.
- KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6638: Too many results returned for the provided postcode.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
If it should only return addresses from the ECOES EES data source. |
|
|
|
|
|
The postcode to search for. |
Query
query AddressUprns(
$after: String,
$before: String,
$electricityOnly: Boolean,
$first: Int,
$last: Int,
$postcode: String!
) {
addressUprns(
after: $after,
before: $before,
electricityOnly: $electricityOnly,
first: $first,
last: $last,
postcode: $postcode
) {
edgeCount
edges {
...AddressUPRNTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"electricityOnly": true,
"first": 10,
"last": 10,
"postcode": "bit-trade-for-lay-rather"
}
Response
{
"data": {
"addressUprns": {
"edgeCount": 45,
"edges": [AddressUPRNTypeEdge],
"pageInfo": PageInfo,
"totalCount": 40
}
}
}
affiliateLink
Type: AffiliateLinkType!
URL: https://api.octopus.energy/v1/graphql/
Link object for an affiliate organization.
Query Complexity: 1
Possible Errors:
- KT-CT-7713: Invalid data.
- KT-CT-7718: Affiliate link is expired.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can create affiliate links
OR Can query affiliate links
OR Can update affiliate links
Arguments
| Name | Description |
|---|---|
|
The affiliate link subdomain. |
Query
query AffiliateLink($subdomain: String!) {
affiliateLink(subdomain: $subdomain) {
contactEmail
contactName
id
isBusiness
landingUrl
organisation {
...AffiliateOrganisationTypeFragment
}
subdomain
trainingStatus
}
}
Variables
{
"subdomain": "season-action-situation-skin-no"
}
Response
{
"data": {
"affiliateLink": {
"contactEmail": "truth-serve-public-impact-news",
"contactName": "threat-down-investment-remember-street",
"id": "16909988",
"isBusiness": true,
"landingUrl": "piece-last-daughter-candidate-still",
"organisation": AffiliateOrganisationType,
"subdomain": "reason-compare-yet-another-what",
"trainingStatus": "NOT_APPLICABLE"
}
}
}
affiliateLinks
Type: [AffiliateLinkType!]!
URL: https://api.octopus.energy/v1/graphql/
Links (urls) for the affiliate organizations.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query affiliate links
Arguments
| Name | Description |
|---|---|
|
Email address of the affiliate agent. |
Query
query AffiliateLinks($agentContactEmail: String!) {
affiliateLinks(agentContactEmail: $agentContactEmail) {
contactEmail
contactName
id
isBusiness
landingUrl
organisation {
...AffiliateOrganisationTypeFragment
}
subdomain
trainingStatus
}
}
Variables
{
"agentContactEmail": "address-where-spring-often-according"
}
Response
{
"data": {
"affiliateLinks": [
{
"contactEmail": "one-despite-doctor-south-foot",
"contactName": "each-lawyer-first-between-ago",
"id": "58616904",
"isBusiness": true,
"landingUrl": "business-upon-citizen-certain-realize",
"organisation": AffiliateOrganisationType,
"subdomain": "term-require-mean-realize-church",
"trainingStatus": "NOT_APPLICABLE"
}
]
}
}
affiliateOrganisation
Type: AffiliateOrganisationType
URL: https://api.octopus.energy/v1/graphql/
Return the details of a given affiliate organization, if any exists.
Query Complexity: 1
Possible Errors:
- KT-CT-7701: The affiliate organisation was not found.
- KT-CT-7702: Either id or number must be provided.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query affiliate organisations
Arguments
| Name | Description |
|---|---|
|
The affiliate organisation ID. |
|
The affiliate organisation number. |
Query
query AffiliateOrganisation(
$id: Int,
$number: String
) {
affiliateOrganisation(
id: $id,
number: $number
) {
allowAlternativePaymentMethods
canRegisterBusinessMeterPoints
canRegisterCustomersWithoutEmailAddress
canRegisterPortfolioAccounts
canRenewTariffs
canUseIvrSupportApi
contactEmail
defaultAccountType
id
isFieldSalesOnlyProduct
name
number
salesChannelCode
skipMeterPointAddressValidation
}
}
Variables
{
"id": 91854863,
"number": "capital-set-investment-place-market"
}
Response
{
"data": {
"affiliateOrganisation": {
"allowAlternativePaymentMethods": true,
"canRegisterBusinessMeterPoints": true,
"canRegisterCustomersWithoutEmailAddress": true,
"canRegisterPortfolioAccounts": true,
"canRenewTariffs": true,
"canUseIvrSupportApi": true,
"contactEmail": "enjoy-economic-minute-sit-decide",
"defaultAccountType": "BUSINESS",
"id": "34996237",
"isFieldSalesOnlyProduct": true,
"name": "vote-professor-while-worker-tonight",
"number": "five-third-road-next-smile",
"salesChannelCode": "chair-plan-animal-cup-close",
"skipMeterPointAddressValidation": true
}
}
}
agentCallCenterStatus
Type: AgentCallCenterStatusType!
URL: https://api.octopus.energy/v1/graphql/
Get the call center status for a given agent.
Query Complexity: 1
Possible Errors:
- KT-CT-7813: Support user not found with that username.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
The support user name. |
Query
query AgentCallCenterStatus($supportUserName: String!) {
agentCallCenterStatus(supportUserName: $supportUserName) {
id
mostRecentCallId
status
updatedAt
}
}
Variables
{
"supportUserName": "fill-but-control-cup-main"
}
Response
{
"data": {
"agentCallCenterStatus": {
"id": "22087101",
"mostRecentCallId": 77480706,
"status": "face-big-perhaps-at-daughter",
"updatedAt": "2022-10-25T13:37:25.142389+00:00"
}
}
}
agreement
Type: CommonAgreementType
URL: https://api.octopus.energy/v1/graphql/
Get an agreement by its ID.
Query Complexity: 1
Possible Errors:
- KT-CT-1501: Agreement not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query agreements
Arguments
| Name | Description |
|---|---|
|
Agreement identifier. |
Query
query Agreement($id: ID!) {
agreement(id: $id) {
account {
...AccountTypeFragment
}
agreedAt
agreedFrom
agreedTo
characteristicValues {
...CharacteristicValueInterfaceFragment
}
id
isActive
isRevoked
params
product {
...SupplyProductTypeFragment
}
ratesAgreedAt
rescissionDeadlineAt
supplyPoint {
...SupplyPointTypeFragment
}
terminatedAt
validFrom
validTo
}
}
Variables
{
"id": "50826353"
}
Response
{
"data": {
"agreement": {
"account": AccountType,
"agreedAt": "1970-03-29T10:30:21.190830+00:00",
"agreedFrom": "1978-11-16T20:17:53.956139+00:00",
"agreedTo": "1973-11-12T09:32:15.223461+00:00",
"characteristicValues": CharacteristicValueInterface,
"id": "60730467",
"isActive": true,
"isRevoked": true,
"params": {"key": "value"},
"product": SupplyProductType,
"ratesAgreedAt": "1980-02-24T12:46:28.261718+00:00",
"rescissionDeadlineAt": "2017-08-23T06:39:43.212998+00:00",
"supplyPoint": SupplyPointType,
"terminatedAt": "2006-03-19T17:11:25.865855+00:00",
"validFrom": "1988-10-19T10:33:32.551354+00:00",
"validTo": "1973-02-15T05:18:27.745760+00:00"
}
}
}
agreementRollover
Type: AgreementRolloverType
URL: https://api.octopus.energy/v1/graphql/
Get an agreement rollover by its number.
Query Complexity: 1
Possible Errors:
- KT-CT-13705: Agreement rollover not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query agreement rollovers
Arguments
| Name | Description |
|---|---|
|
Number of the agreement rollover. |
Query
query AgreementRollover($number: String!) {
agreementRollover(number: $number) {
actualSendDate
agreement {
...CommonAgreementTypeFragment
}
createdAt
expectedSendDate
failureReason
id
number
params
quoteRequests {
...MarketSupplyQuoteRequestTypeFragment
}
rolledOnTo {
...CommonAgreementTypeFragment
}
rolloverType
status
suppressComms
tags
updatedAt
}
}
Variables
{
"number": "full-attention-former-today-religious"
}
Response
{
"data": {
"agreementRollover": {
"actualSendDate": "1987-08-29",
"agreement": CommonAgreementType,
"createdAt": "1998-09-21T12:13:29.258599+00:00",
"expectedSendDate": "2007-01-19",
"failureReason": "during-course-dog-necessary-American",
"id": "14555266",
"number": "whose-adult-reach-investment-throw",
"params": {"key": "value"},
"quoteRequests": [MarketSupplyQuoteRequestType],
"rolledOnTo": CommonAgreementType,
"rolloverType": "DEFAULT",
"status": "PENDING",
"suppressComms": true,
"tags": "than-choice-owner-forward-couple",
"updatedAt": "1985-05-10T00:57:37.533444+00:00"
}
}
}
agreementsForRollover
Type: [CommonAgreementType]
URL: https://api.octopus.energy/v1/graphql/
Get agreements eligible for the rollover process.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query agreements
Arguments
| Name | Description |
|---|---|
|
Days before the agreement expiration. |
|
Window size in days. |
Query
query AgreementsForRollover(
$daysBeforeExpiration: Int!,
$windowSize: Int!
) {
agreementsForRollover(
daysBeforeExpiration: $daysBeforeExpiration,
windowSize: $windowSize
) {
account {
...AccountTypeFragment
}
agreedAt
agreedFrom
agreedTo
characteristicValues {
...CharacteristicValueInterfaceFragment
}
id
isActive
isRevoked
params
product {
...SupplyProductTypeFragment
}
ratesAgreedAt
rescissionDeadlineAt
supplyPoint {
...SupplyPointTypeFragment
}
terminatedAt
validFrom
validTo
}
}
Variables
{
"daysBeforeExpiration": 67,
"windowSize": 4
}
Response
{
"data": {
"agreementsForRollover": [
{
"account": AccountType,
"agreedAt": "2019-10-08T22:33:25.378015+00:00",
"agreedFrom": "1972-11-09T12:10:24.640246+00:00",
"agreedTo": "1989-11-14T22:18:48.843073+00:00",
"characteristicValues": CharacteristicValueInterface,
"id": "40243123",
"isActive": true,
"isRevoked": true,
"params": {"key": "value"},
"product": SupplyProductType,
"ratesAgreedAt": "2025-03-08T03:33:08.600957+00:00",
"rescissionDeadlineAt": "1997-05-01T23:52:49.754753+00:00",
"supplyPoint": SupplyPointType,
"terminatedAt": "1970-05-16T17:56:05.138837+00:00",
"validFrom": "1977-02-01T12:57:18.282489+00:00",
"validTo": "1971-04-15T05:21:05.178413+00:00"
}
]
}
}
allowedSupplyStartDates
Type: [Date]
URL: https://api.octopus.energy/v1/graphql/
A list of dates on which quoted products can start supply.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Arguments
| Name | Description |
|---|---|
|
Whether the quote is for a domestic or business account. Defaults to domestic. |
Query
query AllowedSupplyStartDates($isDomestic: Boolean) {
allowedSupplyStartDates(isDomestic: $isDomestic)
}
Variables
{
"isDomestic": true
}
Response
{
"data": {
"allowedSupplyStartDates": "2002-01-16"
}
}
annualElectricityConsumption
Type: ElectricityConsumptionType!
URL: https://api.octopus.energy/v1/graphql/
The annual electricity consumption data for an MPAN.
Query Complexity: 5
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query annual consumption
Arguments
| Name | Description |
|---|---|
|
The MPAN of the meterpoint to return. |
Query
query AnnualElectricityConsumption($mpan: String!) {
annualElectricityConsumption(mpan: $mpan) {
eac
eacEffectiveFromDate
hasErroneousTransfer
supplierEffectiveFromDate
supplierName
}
}
Variables
{
"mpan": "conference-member-station-item-run"
}
Response
{
"data": {
"annualElectricityConsumption": {
"eac": 171.89,
"eacEffectiveFromDate": "1977-06-14",
"hasErroneousTransfer": true,
"supplierEffectiveFromDate": "2003-12-09",
"supplierName": "color-travel-strategy-sea-TV"
}
}
}
annualGasConsumption
Type: GasConsumptionType!
URL: https://api.octopus.energy/v1/graphql/
The annual gas consumption data for an MPRN.
Query Complexity: 5
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query annual consumption
Arguments
| Name | Description |
|---|---|
|
The MPRN of the meterpoint to return. |
Query
query AnnualGasConsumption($mprn: String!) {
annualGasConsumption(mprn: $mprn) {
aq
aqEffectiveFromDate
supplierEffectiveFromDate
supplierName
}
}
Variables
{
"mprn": "involve-political-itself-until-other"
}
Response
{
"data": {
"annualGasConsumption": {
"aq": 36,
"aqEffectiveFromDate": "1978-11-01",
"supplierEffectiveFromDate": "2011-04-09",
"supplierName": "shoulder-spend-manage-item-somebody"
}
}
}
apiBrownouts
Type: APIBrownoutConnection
URL: https://api.octopus.energy/v1/graphql/
Get brownouts by status.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query api brownouts
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
Statuses to filter for. Otherwise return active and upcoming brownouts. |
|
Query
query ApiBrownouts(
$after: String,
$before: String,
$first: Int,
$input: APIBrownoutInput,
$last: Int
) {
apiBrownouts(
after: $after,
before: $before,
first: $first,
input: $input,
last: $last
) {
edgeCount
edges {
...APIBrownoutEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"input": APIBrownoutInput,
"last": 10
}
Response
{
"data": {
"apiBrownouts": {
"edgeCount": 4,
"edges": [APIBrownoutEdge],
"pageInfo": PageInfo,
"totalCount": 37
}
}
}
apiExceptions
Type: APIExceptionConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get a connection containing API Exceptions.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query api exceptions
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
Fields to filter for. Otherwise don't filter at all. |
|
Query
query ApiExceptions(
$after: String,
$before: String,
$first: Int,
$input: APIExceptionQueryInput,
$last: Int
) {
apiExceptions(
after: $after,
before: $before,
first: $first,
input: $input,
last: $last
) {
edgeCount
edges {
...APIExceptionConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"input": APIExceptionQueryInput,
"last": 10
}
Response
{
"data": {
"apiExceptions": {
"edgeCount": 21,
"edges": [APIExceptionConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 97
}
}
}
applicableRates
Type: ApplicableRateConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-6323: Unauthorized.
- KT-GB-5111: Meter point not found.
- KT-GB-6312: Unable to query unit rates.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Query
query ApplicableRates(
$accountNumber: String!,
$after: String,
$before: String,
$endAt: DateTime!,
$first: Int,
$last: Int,
$mpxn: String!,
$startAt: DateTime!
) {
applicableRates(
accountNumber: $accountNumber,
after: $after,
before: $before,
endAt: $endAt,
first: $first,
last: $last,
mpxn: $mpxn,
startAt: $startAt
) {
edgeCount
edges {
...ApplicableRateConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-3953AEC6",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"endAt": "2013-02-10T00:58:11.539266+00:00",
"first": 10,
"last": 10,
"mpxn": "there-officer-southern-once-table",
"startAt": "1987-03-03T02:15:11.065361+00:00"
}
Response
{
"data": {
"applicableRates": {
"edgeCount": 95,
"edges": [ApplicableRateConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 58
}
}
}
appSessions
Type: AppSessionConnectionTypeConnection!
URL: https://api.octopus.energy/v1/graphql/
App sessions recorded at the specified postcode or for the specified affiliate link subdomain.
Query Complexity: 1
Possible Errors:
- KT-CT-4410: Invalid postcode.
- KT-CT-7713: Invalid data.
- KT-CT-7723: Must supply postcode or subdomain.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query affiliate app sessions
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
The postcode of the address at which the app session was recorded. |
|
The affiliate link subdomain to filter app sessions by. |
Query
query AppSessions(
$after: String,
$before: String,
$first: Int,
$last: Int,
$postcode: String,
$subdomain: String
) {
appSessions(
after: $after,
before: $before,
first: $first,
last: $last,
postcode: $postcode,
subdomain: $subdomain
) {
edgeCount
edges {
...AppSessionConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"postcode": "maintain-war-two-quality-actually",
"subdomain": "particularly-agreement-big-movement-few"
}
Response
{
"data": {
"appSessions": {
"edgeCount": 56,
"edges": [AppSessionConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 37
}
}
}
authorizedApplications
Type: [AuthorizedApplication]
URL: https://api.octopus.energy/v1/graphql/
Get all the confidential-client applications the current user has authorized.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query AuthorizedApplications {
authorizedApplications {
clientId
name
}
}
Response
{
"data": {
"authorizedApplications": [
{
"clientId": "12117205",
"name": "position-national-simply-defense-ten"
}
]
}
}
autoTopupConfigs
Type: AutoTopupConfigConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get the auto top-up configs for a device. Ordered by effective from date, latest first.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Target account number, e.g. 'A-A1B2C3D4'. |
|
|
|
|
|
Target device ID, e.g. 'A1-BC-D2-00-01-23-EF-4G'. |
|
The datetime from which the auto top-up is effective, e.g. '2024-01-01T00:00:00+00:00'. |
|
|
|
Query
query AutoTopupConfigs(
$accountNumber: String!,
$after: String,
$before: String,
$deviceId: String!,
$effectiveFrom: DateTime,
$first: Int,
$last: Int
) {
autoTopupConfigs(
accountNumber: $accountNumber,
after: $after,
before: $before,
deviceId: $deviceId,
effectiveFrom: $effectiveFrom,
first: $first,
last: $last
) {
edges {
...AutoTopupConfigConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
}
}
Variables
{
"accountNumber": "A-AD542903",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"deviceId": "72202371",
"effectiveFrom": "2000-09-07T19:49:27.897097+00:00",
"first": 10,
"last": 10
}
Response
{
"data": {
"autoTopupConfigs": {
"edges": [AutoTopupConfigConnectionTypeEdge],
"pageInfo": PageInfo
}
}
}
autoTopupTriggers
Type: AutoTopupTriggerConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get auto top-up trigger events for an auto topup config. Ordered by triggered_at datetime, latest first.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
Target auto top-up config ID, e.g. '123'. |
|
|
|
Filter by failure reason of the auto top-up trigger event. |
|
|
|
|
|
Filter by source of the auto top-up trigger event. |
|
Filter by status of the auto top-up trigger event. |
|
Filter by datetime (inclusive) from which trigger events have occurred, e.g. '2024-01-01T00:00:00+00:00'. |
Query
query AutoTopupTriggers(
$after: String,
$autoTopupConfigId: ID!,
$before: String,
$failureReason: SmartDeviceAutoTopupTriggerFailureReasons,
$first: Int,
$last: Int,
$source: SmartDeviceAutoTopupTriggerSources,
$status: SmartDeviceAutoTopupTriggerStatus,
$triggersFrom: DateTime
) {
autoTopupTriggers(
after: $after,
autoTopupConfigId: $autoTopupConfigId,
before: $before,
failureReason: $failureReason,
first: $first,
last: $last,
source: $source,
status: $status,
triggersFrom: $triggersFrom
) {
edges {
...AutoTopupTriggerConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"autoTopupConfigId": "92088842",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"failureReason": "NO_IMPORT_METER",
"first": 10,
"last": 10,
"source": "LOW_CREDIT_BALANCE",
"status": "INITIATED",
"triggersFrom": "2005-10-24T23:14:40.095653+00:00"
}
Response
{
"data": {
"autoTopupTriggers": {
"edges": [AutoTopupTriggerConnectionTypeEdge],
"pageInfo": PageInfo
}
}
}
availableOfferings
Type: [OfferingType]
URL: https://api.octopus.energy/v1/graphql/
Get a list of actively available offerings from the catalog.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query catalog offerings
Query
query AvailableOfferings {
availableOfferings {
customerDescription
customerName
groups {
...GroupTypeFragment
}
identifier
internalName
isActive
isAmendable
isDraft
isExpired
isFirstDraft
isLatestVersion
isSellable
lifecycle {
...LifecycleTypeFragment
}
offeringComponents {
...OfferingComponentTypeFragment
}
productComponents {
...ProductComponentTypeFragment
}
tags {
...TagTypeFragment
}
termTemplateComponents {
...TermTemplateComponentTypeFragment
}
}
}
Response
{
"data": {
"availableOfferings": [
{
"customerDescription": "one-party-experience-cover-family",
"customerName": "kid-go-truth-project-it",
"groups": [GroupType],
"identifier": "63880571",
"internalName": "worker-something-southern-full-budget",
"isActive": true,
"isAmendable": true,
"isDraft": true,
"isExpired": true,
"isFirstDraft": true,
"isLatestVersion": true,
"isSellable": true,
"lifecycle": LifecycleType,
"offeringComponents": [OfferingComponentType],
"productComponents": [ProductComponentType],
"tags": [TagType],
"termTemplateComponents": [TermTemplateComponentType]
}
]
}
}
availableProductFromDisplayName
Type: EnergyProductType
URL: https://api.octopus.energy/v1/graphql/
Available energy product, whose display name has the given prefix.
Query Complexity: 1
Possible Errors:
- KT-GB-9514: No available product found.
- KT-GB-9515: Multiple available products found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Display name of the product. |
Query
query AvailableProductFromDisplayName($displayName: String!) {
availableProductFromDisplayName(displayName: $displayName) {
availableFrom
availableTo
code
description
direction
displayName
endsAt
exitFees
exitFeesType
fullName
id
includesEpgReduction
isAvailable
isBusiness
isChargedHalfHourly
isDefault
isDomestic
isFixed
isGreen
isHidden
isOccupier
isPrepay
isUnavailable
isVariable
notes
tags
tariffs {
...EnergyTariffConnectionTypeConnectionFragment
}
term
}
}
Variables
{
"displayName": "usually-popular-box-president-student"
}
Response
{
"data": {
"availableProductFromDisplayName": {
"availableFrom": "1979-02-14T16:44:47.439892+00:00",
"availableTo": "1997-08-31T16:13:50.086134+00:00",
"code": "meeting-reason-start-young-mother",
"description": "magazine-record-reflect-statement-start",
"direction": "IMPORT",
"displayName": "low-difference-result-talk-health",
"endsAt": "1972-05-24T18:57:01.357759+00:00",
"exitFees": 13,
"exitFeesType": "assume-film-increase-realize-evening",
"fullName": "writer-set-particular-style-white",
"id": "83510860",
"includesEpgReduction": true,
"isAvailable": true,
"isBusiness": true,
"isChargedHalfHourly": true,
"isDefault": true,
"isDomestic": true,
"isFixed": true,
"isGreen": true,
"isHidden": true,
"isOccupier": true,
"isPrepay": true,
"isUnavailable": true,
"isVariable": true,
"notes": "drive-area-space-themselves-school",
"tags": "record-mention-check-phone-agreement",
"tariffs": EnergyTariffConnectionTypeConnection,
"term": 11
}
}
}
availableProducts
Type: [SupplyProductType]
URL: https://api.octopus.energy/v1/graphql/
Get available products for the given market.
Query Complexity: 1
Possible Errors:
- KT-CT-4930: Unsupported market.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query available products
Arguments
| Name | Description |
|---|---|
|
Products available for the target market. |
Query
query AvailableProducts($marketName: String!) {
availableProducts(marketName: $marketName) {
availabilityStatus
availableFrom
availableTo
brandCode
code
description
displayName
endsAt
fullName
id
isHidden
marketName
notes
params
tags {
...SupplyProductTagTypeFragment
}
term
termsAndConditionsTypes {
...TermsAndConditionsTypeFragment
}
termsContractType
}
}
Variables
{
"marketName": "simple-employee-answer-reduce-later"
}
Response
{
"data": {
"availableProducts": [
{
"availabilityStatus": "EVERYONE",
"availableFrom": "2015-08-03T22:11:29.717371+00:00",
"availableTo": "1985-01-21T21:44:44.108870+00:00",
"brandCode": "gas-tax-service-half-Mrs",
"code": "through-provide-discussion-mention-become",
"description": "fire-experience-development-watch-everybody",
"displayName": "enter-charge-group-yeah-process",
"endsAt": "2016-04-28T12:07:32.312510+00:00",
"fullName": "sport-expect-try-war-any",
"id": "82583349",
"isHidden": true,
"marketName": "yeah-social-north-blue-truth",
"notes": "billion-feel-smile-method-successful",
"params": {"key": "value"},
"tags": [SupplyProductTagType],
"term": 97,
"termsAndConditionsTypes": [TermsAndConditionsType],
"termsContractType": "generation-recognize-relationship-each-hour"
}
]
}
}
availableProductsForMeterPoint
Type: [MPxNProductType]
URL: https://api.octopus.energy/v1/graphql/
A list of product codes that are the currently available products for a meter point.
Query Complexity: 1
Possible Errors:
- KT-GB-4118: Invalid MPxN.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
|
|
|
Include products with a restricted availability in the results. |
|
A list of MPxNs. |
Query
query AvailableProductsForMeterPoint(
$accountNumber: String!,
$availableAt: DateTime!,
$includeRestrictedProducts: Boolean,
$mpxns: [String]!
) {
availableProductsForMeterPoint(
accountNumber: $accountNumber,
availableAt: $availableAt,
includeRestrictedProducts: $includeRestrictedProducts,
mpxns: $mpxns
) {
mpxn
products {
...EnergyProductTypeFragment
}
}
}
Variables
{
"accountNumber": "A-C2213399",
"availableAt": "1979-10-06T06:16:20.378515+00:00",
"includeRestrictedProducts": true,
"mpxns": "travel-enough-hour-use-still"
}
Response
{
"data": {
"availableProductsForMeterPoint": [
{
"mpxn": "heart-buy-material-remain-deal",
"products": [EnergyProductType]
}
]
}
}
availableProductSwitchDates
Type: [Date]
URL: https://api.octopus.energy/v1/graphql/
Get available dates for product switch.
Query Complexity: 1
Possible Errors:
- KT-CT-1501: Agreement not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can switch product
Arguments
| Name | Description |
|---|---|
|
Agreement ID. |
|
The maximum number of days to look for available dates. |
Query
query AvailableProductSwitchDates(
$agreementId: Int!,
$maxRange: Int
) {
availableProductSwitchDates(
agreementId: $agreementId,
maxRange: $maxRange
)
}
Variables
{
"agreementId": 16103272,
"maxRange": 42
}
Response
{
"data": {
"availableProductSwitchDates": "2008-09-21"
}
}
backendScreen
Type: BackendScreenType
URL: https://api.octopus.energy/v1/graphql/
Get mobile screen details to render.
Query Complexity: 1
Possible Errors:
- KT-CT-8001: No backend screen available.
- KT-CT-8005: Backend screen does not support parameters.
- KT-CT-8006: Error applying parameters to backend screen.
- KT-CT-8008: Incorrect or missing data necessary to build the screen.
- KT-CT-8009: Error translating screen content.
- KT-CT-8010: Invalid step ID.
- KT-CT-8011: Cannot rewind past a previous irreversible step.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The maximum version of backend screens supported by the client. |
|
List of key-value pairs (strings) to pass as parameters to the screen. |
|
The ID of the screen to return. |
Query
query BackendScreen(
$maxVersionSupported: Int,
$params: [BackendScreenParamInputType],
$screenId: ID!
) {
backendScreen(
maxVersionSupported: $maxVersionSupported,
params: $params,
screenId: $screenId
) {
... on ComponentListType {
...ComponentListTypeFragment
}
... on Dashboard {
...DashboardFragment
}
... on FormScreenType {
...FormScreenTypeFragment
}
... on GenericBackendScreen {
...GenericBackendScreenFragment
}
}
}
Variables
{
"maxVersionSupported": 71,
"params": BackendScreenParamInputType,
"screenId": "61400297"
}
Response
{
"data": {
"backendScreen": ComponentListType
}
}
backendScreenEventIds
Type: [String]
URL: https://api.octopus.energy/v1/graphql/
Get all registered backend screen event IDs.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query BackendScreenEventIds {
backendScreenEventIds
}
Response
{
"data": {
"backendScreenEventIds": "radio-pay-total-stop-whatever"
}
}
backendScreenIds
Type: [String]
URL: https://api.octopus.energy/v1/graphql/
Get all registered backend screen IDs.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query BackendScreenIds {
backendScreenIds
}
Response
{
"data": {
"backendScreenIds": "mouth-include-herself-morning-resource"
}
}
balanceForecast
Type: BalanceForecastType
URL: https://api.octopus.energy/v1/graphql/
The balance forecast for an account.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
Query
query BalanceForecast($accountNumber: String!) {
balanceForecast(accountNumber: $accountNumber) {
availability {
...BalanceForecastAvailabilityTypeFragment
}
}
}
Variables
{
"accountNumber": "A-B7F78A8F"
}
Response
{
"data": {
"balanceForecast": {
"availability": BalanceForecastAvailabilityType
}
}
}
bankDetailsValidation
Type: BankDetailsValidationResult
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Rate Limits
| Key | Steps |
|---|---|
Ip |
['65/m'] |
Arguments
| Name | Description |
|---|---|
|
The IBAN of the bank account. |
Query
query BankDetailsValidation($iban: NonEmptyString!) {
bankDetailsValidation(iban: $iban) {
areValid
message
}
}
Variables
{
"iban": "television-wife-whether-any-generation"
}
Response
{
"data": {
"bankDetailsValidation": {
"areValid": true,
"message": "meet-city-feel-one-arm"
}
}
}
batteryDevice
Type: BatteryDeviceType
URL: https://api.octopus.energy/v1/graphql/
The currently active battery device.
Query Complexity: 2
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'batteryDevice' field is deprecated.
Use `SmartFlexInverter` on `devices` query instead.
- Marked as deprecated on 2025-09-08.
- Scheduled for removal on or after 2026-03-01.
You can read more about this deprecation on:
https://announcements.kraken.tech/announcements/public/676/
Query
query BatteryDevice(
$accountNumber: String!,
$propertyId: Int!
) {
batteryDevice(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
chargingPreferences {
...BatteryChargingPreferencesTypeFragment
}
deviceStatus {
...DeviceStatusTypeFragment
}
deviceType
krakenflexDeviceId
params {
...BatteryParamsTypeFragment
}
provider
}
}
Variables
{
"accountNumber": "A-706AFA56",
"propertyId": 93310216
}
Response
{
"data": {
"batteryDevice": {
"chargingPreferences": BatteryChargingPreferencesType,
"deviceStatus": DeviceStatusType,
"deviceType": "BATTERIES",
"krakenflexDeviceId": "76617288",
"params": BatteryParamsType,
"provider": "BYD"
}
}
}
batteryVariants
Type: [BatteryVariantsType]
URL: https://api.octopus.energy/v1/graphql/
All supported batteries and their details.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Arguments
| Name | Description |
|---|---|
|
Only return batteries of a specific make. |
Query
query BatteryVariants($make: String) {
batteryVariants(make: $make) {
make
models {
...BatteryVariantModelsTypeFragment
}
}
}
Variables
{
"make": "be-media-stay-garden-those"
}
Response
{
"data": {
"batteryVariants": [
{
"make": "provide-half-actually-possible-half",
"models": [BatteryVariantModelsType]
}
]
}
}
billingTriggerConfigurations
Type: BillingTriggerConfigurationsConnection
URL: https://api.octopus.energy/v1/graphql/
Query billing trigger configurations for a specific target. By default returns only active configurations. Specify effective_from/effective_to for time range filtering. Use include_children=true on parent target to get configurations for all child targets.
Query Complexity: 1
Possible Errors:
- KT-CT-9706: Invalid billing trigger target input.
- KT-CT-9707: includeChildren cannot be used with effectiveFrom or effectiveTo parameters.
- KT-CT-9708: Both effectiveFrom and effectiveTo must be provided to filter by period.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query billing information
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Start of the time range to query configurations for. |
|
End of the time range to query configurations for. |
|
|
|
Include all child targets of the specified target. |
|
|
|
The target to query configurations for. |
Query
query BillingTriggerConfigurations(
$after: String,
$before: String,
$effectiveFrom: DateTime,
$effectiveTo: DateTime,
$first: Int,
$includeChildren: Boolean,
$last: Int,
$target: TargetInput!
) {
billingTriggerConfigurations(
after: $after,
before: $before,
effectiveFrom: $effectiveFrom,
effectiveTo: $effectiveTo,
first: $first,
includeChildren: $includeChildren,
last: $last,
target: $target
) {
edgeCount
edges {
...BillingTriggerConfigurationsEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"effectiveFrom": "1990-11-16T01:41:10.129540+00:00",
"effectiveTo": "2012-06-23T09:44:02.501632+00:00",
"first": 10,
"includeChildren": true,
"last": 10,
"target": TargetInput
}
Response
{
"data": {
"billingTriggerConfigurations": {
"edgeCount": 23,
"edges": [BillingTriggerConfigurationsEdge],
"pageInfo": PageInfo,
"totalCount": 33
}
}
}
business
Type: BusinessType
URL: https://api.octopus.energy/v1/graphql/
Get details about a business.
Query Complexity: 1
Possible Errors:
- KT-CT-11101: The viewer is not authorized to execute the query/mutation. Check the ownership/permissions of provided data.
- KT-CT-11107: Unauthorized.
- KT-CT-1605: Invalid input.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query businesses
Arguments
| Name | Description |
|---|---|
|
List of business detail key-value pairs to filter by. |
|
Kraken-generated, human-readable number for display purposes. |
|
The business ID. |
Query
query Business(
$details: [BusinessDetailInput],
$displayableNumber: String,
$id: ID
) {
business(
details: $details,
displayableNumber: $displayableNumber,
id: $id
) {
billingAddress {
...RichAddressTypeFragment
}
businessType
details {
...BusinessDetailTypeFragment
}
displayableNumber
id
legalAddress {
...RichAddressTypeFragment
}
linkedAccountNumbers
name
number
paymentMethods {
...PaymentInstructionConnectionTypeConnectionFragment
}
sectors
segmentName
}
}
Variables
{
"details": BusinessDetailInput,
"displayableNumber": "piece-main-protect-up-available",
"id": "69240031"
}
Response
{
"data": {
"business": {
"billingAddress": RichAddressType,
"businessType": "SOLE_TRADER",
"details": [BusinessDetailType],
"displayableNumber": "PM-provide-different-rest-down",
"id": "19415065",
"legalAddress": RichAddressType,
"linkedAccountNumbers": "49947440",
"name": "perform-home-that-expect-less",
"number": "everything-environment-list-receive-option",
"paymentMethods": PaymentInstructionConnectionTypeConnection,
"sectors": None,
"segmentName": "agent-million-whose-attorney-each"
}
}
}
businessAccountReferralRewardScheme
Type: ReferralSchemeType
URL: https://api.octopus.energy/v1/graphql/
Return a business referral reward scheme for the given account referral code.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Friend referral code. |
Query
query BusinessAccountReferralRewardScheme($code: String!) {
businessAccountReferralRewardScheme(code: $code) {
canBeReferred
code
combinedRewardAmount
isUsageAtCapacity
loyaltyPointsBonus
maxRecurrence
referralDisplayUrl
referralUrl
referredRewardAmount
referrerGivenName
referrerRewardAmount
schemeType
}
}
Variables
{
"code": "financial-board-computer-return-military"
}
Response
{
"data": {
"businessAccountReferralRewardScheme": {
"canBeReferred": true,
"code": "likely-guy-sense-sense-it",
"combinedRewardAmount": 30,
"isUsageAtCapacity": true,
"loyaltyPointsBonus": 22,
"maxRecurrence": 63,
"referralDisplayUrl": "however-minute-near-though-street",
"referralUrl": "hope-imagine-scene-article-event",
"referredRewardAmount": 6,
"referrerGivenName": "Sherri",
"referrerRewardAmount": 35,
"schemeType": "each-even-deal-while-difficult"
}
}
}
businessContract
Type: Contract
URL: https://api.octopus.energy/v1/graphql/
Get details about an account contract.
Query Complexity: 1
Possible Errors:
- KT-CT-10003: Contract not found.
- KT-CT-10005: Missing required parameter: either identifier or accountNumber must be provided.
- KT-CT-10006: Account not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query contracts
Arguments
| Name | Description |
|---|---|
|
The account number to find the business contract for. |
|
The identifier of the contract. |
|
The version of the contract. |
Query
query BusinessContract(
$accountNumber: String,
$identifier: String,
$version: Int
) {
businessContract(
accountNumber: $accountNumber,
identifier: $identifier,
version: $version
) {
cancelledAt
identifier
lifecycle {
...ContractVersionFragment
}
notes {
...ContractNoteTypeFragment
}
party {
... on AccountType {
...AccountTypeFragment
}
... on BusinessType {
...BusinessTypeFragment
}
}
rescindedAt
signedAt
status
subject {
...AccountTypeFragment
}
terms {
...TermInterfaceFragment
}
title
validFrom
validTo
}
}
Variables
{
"accountNumber": "A-791BA251",
"identifier": "82061625",
"version": 49
}
Response
{
"data": {
"businessContract": {
"cancelledAt": "1986-04-13T06:04:38.761716+00:00",
"identifier": "26703273",
"lifecycle": ContractVersion,
"notes": [ContractNoteType],
"party": AccountType,
"rescindedAt": "1997-11-14T11:58:06.767985+00:00",
"signedAt": "1976-05-08T20:24:02.233690+00:00",
"status": "REVOKED",
"subject": [AccountType],
"terms": TermInterface,
"title": "side-firm-power-second-wish",
"validFrom": "1977-05-29T13:21:22.778542+00:00",
"validTo": "2003-07-31T13:07:36.884914+00:00"
}
}
}
call
Type: CallInterface!
URL: https://api.octopus.energy/v1/graphql/
Get a call using an integer or UUID identifier.
Query Complexity: 2
Possible Errors:
- KT-CT-11802: Call not found.
- KT-CT-11817: Invalid call ID.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
Identifier for the call, as an integer or a UUID. |
Query
query Call($id: ID!) {
call(id: $id) {
account {
...AccountTypeFragment
}
id
metadata {
...CallMetadataItemTypeFragment
}
}
}
Variables
{
"id": "24588286"
}
Response
{
"data": {
"call": {
"account": AccountType,
"id": "65092345",
"metadata": [CallMetadataItemType]
}
}
}
callRecordingDetail
Type: CallRecordingDetailType!
URL: https://api.octopus.energy/v1/graphql/
Get recording detail for a call and call recording.
Query Complexity: 2
Possible Errors:
- KT-CT-11822: Recording detail incomplete.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
The voice vendor managing the call. |
|
Unique ID of the call in the vendor's system. |
Query
query CallRecordingDetail(
$vendor: VoiceVendor!,
$vendorRecordingId: ID!
) {
callRecordingDetail(
vendor: $vendor,
vendorRecordingId: $vendorRecordingId
) {
endTime
fromPhoneNumber
primaryAgentEmail
startTime
toPhoneNumber
}
}
Variables
{
"vendor": "TWILIO",
"vendorRecordingId": "98412184"
}
Response
{
"data": {
"callRecordingDetail": {
"endTime": "2018-05-27T11:30:45.107635+00:00",
"fromPhoneNumber": "physical-never-already-wear-bill",
"primaryAgentEmail": "ok-product-seat-just-note",
"startTime": "1995-03-29T16:39:09.873359+00:00",
"toPhoneNumber": "pick-action-material-summer-method"
}
}
}
callTag
Type: CallTagType!
URL: https://api.octopus.energy/v1/graphql/
Get the call tag for a given ID.
Query Complexity: 2
Possible Errors:
- KT-CT-11809: Call tag not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
The call tag ID. |
Query
query CallTag($id: ID!) {
callTag(id: $id) {
id
isActive
name
}
}
Variables
{
"id": "11106155"
}
Response
{
"data": {
"callTag": {
"id": "76393065",
"isActive": true,
"name": "address-music-role-property-off"
}
}
}
callTags
Type: CallTagConnectionTypeConnection!
URL: https://api.octopus.energy/v1/graphql/
Get call tags.
Query Complexity: 2
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
Filter by active status. |
|
|
|
Filter by call tag name. |
Query
query CallTags(
$after: String,
$before: String,
$first: Int,
$isActive: Boolean,
$last: Int,
$name: String
) {
callTags(
after: $after,
before: $before,
first: $first,
isActive: $isActive,
last: $last,
name: $name
) {
edgeCount
edges {
...CallTagConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"isActive": true,
"last": 10,
"name": "get-side-trouble-debate-low"
}
Response
{
"data": {
"callTags": {
"edgeCount": 1,
"edges": [CallTagConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 27
}
}
}
callTranscripts
Type: CallTranscriptConnectionTypeConnection!
URL: https://api.octopus.energy/v1/graphql/
Get all non-deleted transcripts for the given call, newest first. In-progress and failed transcripts are included for diagnostic visibility but their download field will be null.
Query Complexity: 2
Possible Errors:
- KT-CT-11802: Call not found.
- KT-CT-11817: Invalid call ID.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query call transcripts
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Identifier for the call, as an integer or a UUID. |
|
|
|
Query
query CallTranscripts(
$after: String,
$before: String,
$callId: ID!,
$first: Int,
$last: Int
) {
callTranscripts(
after: $after,
before: $before,
callId: $callId,
first: $first,
last: $last
) {
edgeCount
edges {
...CallTranscriptConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"callId": "93270714",
"first": 10,
"last": 10
}
Response
{
"data": {
"callTranscripts": {
"edgeCount": 93,
"edges": [CallTranscriptConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 48
}
}
}
callTranscriptsInWindow
Type: CallTranscriptConnectionTypeConnection!
URL: https://api.octopus.energy/v1/graphql/
Get all completed transcripts whose transcribed_at falls within a time window.
Query Complexity: 6
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query call transcripts
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
Only transcripts where transcribed_at is at or after this datetime. |
|
Only transcripts where transcribed_at is at or before this datetime. Defaults to the current time when omitted. |
Query
query CallTranscriptsInWindow(
$after: String,
$before: String,
$first: Int,
$last: Int,
$transcribedAfter: DateTime!,
$transcribedBefore: DateTime
) {
callTranscriptsInWindow(
after: $after,
before: $before,
first: $first,
last: $last,
transcribedAfter: $transcribedAfter,
transcribedBefore: $transcribedBefore
) {
edgeCount
edges {
...CallTranscriptConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"transcribedAfter": "2012-08-27T17:58:07.145738+00:00",
"transcribedBefore": "1972-06-26T12:09:41.143516+00:00"
}
Response
{
"data": {
"callTranscriptsInWindow": {
"edgeCount": 47,
"edges": [CallTranscriptConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 31
}
}
}
campaigns
Type: AccountCampaignConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
The campaigns associated with this account.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query account campaigns
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
|
|
|
|
|
|
Query
query Campaigns(
$accountNumber: String!,
$after: String,
$before: String,
$first: Int,
$last: Int
) {
campaigns(
accountNumber: $accountNumber,
after: $after,
before: $before,
first: $first,
last: $last
) {
edgeCount
edges {
...AccountCampaignConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-BD55C6F8",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10
}
Response
{
"data": {
"campaigns": {
"edgeCount": 3,
"edges": [AccountCampaignConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 7
}
}
}
cancelEnrolmentData
Type: CancelEnrolmentDataType
URL: https://api.octopus.energy/v1/graphql/
Data required for the cancel enrollment journey.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
- KT-GB-1503: The account's enrollment has already been cancelled.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
Query
query CancelEnrolmentData($accountNumber: String!) {
cancelEnrolmentData(accountNumber: $accountNumber) {
canBeDelayed
canBeWithdrawn
canSkipSsdPayment
currentEstimatedSsd
earliestPossibleSsd
latestPossibleSsd
}
}
Variables
{
"accountNumber": "A-D12FAFA5"
}
Response
{
"data": {
"cancelEnrolmentData": {
"canBeDelayed": true,
"canBeWithdrawn": true,
"canSkipSsdPayment": true,
"currentEstimatedSsd": "2004-03-08",
"earliestPossibleSsd": "2020-11-10",
"latestPossibleSsd": "2025-10-26"
}
}
}
canRescindAgreement
Type: Boolean
URL: https://api.octopus.energy/v1/graphql/
Check if an agreement can be rescinded.
Query Complexity: 1
Possible Errors:
- KT-CT-1501: Agreement not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query agreement rescissions
Arguments
| Name | Description |
|---|---|
|
The ID of the agreement to check. |
Query
query CanRescindAgreement($agreementId: Int!) {
canRescindAgreement(agreementId: $agreementId)
}
Variables
{
"agreementId": 12134784
}
Response
{
"data": {
"canRescindAgreement": true
}
}
caredForAccounts
Type: [String!]!
URL: https://api.octopus.energy/v1/graphql/
The account numbers of the accounts that the user is caring for.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'caredForAccounts' field is deprecated.
The octocare feature is no longer supported.
- Marked as deprecated on 2026-04-22.
- Scheduled for removal on or after 2026-10-22.
Query
query CaredForAccounts {
caredForAccounts
}
Response
{
"data": {
"caredForAccounts": "project-opportunity-suggest-cell-TV"
}
}
chargePointVariants
Type: [ChargePointVariantType]
URL: https://api.octopus.energy/v1/graphql/
All charge points variants.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Deprecated
The 'chargePointVariants' field is deprecated.
Please use 'flexSupportedDevices' instead.
- Marked as deprecated on 2026-04-15.
- Scheduled for removal on or after 2026-10-15.
Query
query ChargePointVariants {
chargePointVariants {
make
models {
...ChargePointVariantModelTypeFragment
}
}
}
Response
{
"data": {
"chargePointVariants": [
{
"make": "high-especially-unit-want-inside",
"models": [ChargePointVariantModelType]
}
]
}
}
collectionProcessDetails
Type: CollectionProcessDetailsType
URL: https://api.octopus.energy/v1/graphql/
Collection process record details.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-11201: No Collection Process Records associated with id.
- KT-CT-11206: Unable to retrieve disconnection related data for collection process.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The collection process record number. |
Query
query CollectionProcessDetails($collectionProcessRecordNumber: String!) {
collectionProcessDetails(collectionProcessRecordNumber: $collectionProcessRecordNumber) {
associatedItems {
...CollectionProcessRecordAssociatedItemTypeFragment
}
collectionProcessRecordNumber
collectionProcessType
completionType
isActive
isComplete
isPaused
pausedDays
targetObjectIdentifier
}
}
Variables
{
"collectionProcessRecordNumber": "suffer-actually-safe-task-easy"
}
Response
{
"data": {
"collectionProcessDetails": {
"associatedItems": [CollectionProcessRecordAssociatedItemType],
"collectionProcessRecordNumber": "huge-able-something-actually-kind",
"collectionProcessType": "ACCOUNT",
"completionType": "art-hundred-bill-citizen-then",
"isActive": true,
"isComplete": true,
"isPaused": true,
"pausedDays": 80,
"targetObjectIdentifier": "33793003"
}
}
}
complaint
Type: ComplaintType
URL: https://api.octopus.energy/v1/graphql/
Get a complaint.
Query Complexity: 1
Possible Errors:
- KT-CT-12301: Complaint not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query complaints
Arguments
| Name | Description |
|---|---|
|
Query
query Complaint($complaintId: Int!) {
complaint(complaintId: $complaintId) {
assigneeId
contacts {
...ComplaintContactConnectionTypeConnectionFragment
}
creationDate
id
isOfficial
resolutionDate
subtype
type
}
}
Variables
{
"complaintId": 59466712
}
Response
{
"data": {
"complaint": {
"assigneeId": "20702326",
"contacts": ComplaintContactConnectionTypeConnection,
"creationDate": "2018-05-15",
"id": "10497551",
"isOfficial": true,
"resolutionDate": "1988-06-24",
"subtype": "example-yard-firm-point-into",
"type": "reason-activity-its-necessary-answer"
}
}
}
completedDispatches
Type: [UpsideDispatchType]
URL: https://api.octopus.energy/v1/graphql/
All completed device dispatches 12 hours behind, in reverse time order.
Query Complexity: 3
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4341: Unable to fetch completed dispatches.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can access third party queries
OR Can view ev data
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Arguments
| Name | Description |
|---|---|
|
Query
query CompletedDispatches($accountNumber: String!) {
completedDispatches(accountNumber: $accountNumber) {
delta
end
meta {
...UpsideDispatchMetaTypeFragment
}
start
}
}
Variables
{
"accountNumber": "A-C8A5BC79"
}
Response
{
"data": {
"completedDispatches": [
{
"delta": "1.0",
"end": "2020-10-28T01:16:30.614988+00:00",
"meta": UpsideDispatchMetaType,
"start": "2023-02-14T01:06:34.878693+00:00"
}
]
}
}
consentTypes
Type: [ConsentTypeType]
URL: https://api.octopus.energy/v1/graphql/
A list of the consent types available.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query ConsentTypes {
consentTypes {
code
defaultValue
description
name
}
}
Response
{
"data": {
"consentTypes": [
{
"code": "late-relate-stock-generation-fund",
"defaultValue": "ACCEPTED",
"description": "after-something-military-table-increase",
"name": "same-board-food-major-occur"
}
]
}
}
consumptionEstimates
Type: ConsumptionEstimates
URL: https://api.octopus.energy/v1/graphql/
Consumption estimates based on ofgem statistics.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query ConsumptionEstimates {
consumptionEstimates {
high {
...ConsumptionEstimateFragment
}
low {
...ConsumptionEstimateFragment
}
medium {
...ConsumptionEstimateFragment
}
}
}
Response
{
"data": {
"consumptionEstimates": {
"high": ConsumptionEstimate,
"low": ConsumptionEstimate,
"medium": ConsumptionEstimate
}
}
}
contractCreationJourney
Type: ContractCreationJourneyType
URL: https://api.octopus.energy/v1/graphql/
Get details about a contract creation journey.
Query Complexity: 1
Possible Errors:
- KT-CT-10017: The contract journey could not be found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query contracts AND Can query contract journeys
Arguments
| Name | Description |
|---|---|
|
The number of the contract journey. |
Query
query ContractCreationJourney($number: String!) {
contractCreationJourney(number: $number) {
context {
...ContractCreationContextFragment
}
contractDetails {
...ContractDetailsFragment
}
journeyType
notes {
...ContractNoteTypeFragment
}
number
orderReference
requestedAt
status
}
}
Variables
{
"number": "section-then-right-last-research"
}
Response
{
"data": {
"contractCreationJourney": {
"context": ContractCreationContext,
"contractDetails": ContractDetails,
"journeyType": "CONTRACT_CREATION",
"notes": [ContractNoteType],
"number": "hear-admit-figure-lose-note",
"orderReference": "interesting-administration-his-which-risk",
"requestedAt": "1987-06-19T04:06:43.146881+00:00",
"status": "IN_PROGRESS"
}
}
}
contractNoteReasons
Type: [ContractNoteReasonType]
URL: https://api.octopus.energy/v1/graphql/
Get a list of contract note reasons, optionally filtered by activity types.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query contract note reasons
Arguments
| Name | Description |
|---|---|
|
Filter reasons applicable to any of the given contract activity types. |
Query
query ContractNoteReasons($activityTypes: [ContractActivityTypeOptions]) {
contractNoteReasons(activityTypes: $activityTypes) {
activityTypes
description
slug
}
}
Variables
{
"activityTypes": "ALL_ACTIVITY_TYPES"
}
Response
{
"data": {
"contractNoteReasons": [
{
"activityTypes": "ALL_ACTIVITY_TYPES",
"description": "sound-effort-actually-up-PM",
"slug": "share-traditional-require-full-race"
}
]
}
}
contracts
Type: [Contract]
URL: https://api.octopus.energy/v1/graphql/
Get a list of contracts filtered by party or subject.
Query Complexity: 1
Possible Errors:
- KT-CT-10029: Missing contract filters.
- KT-CT-10030: Filter by subject is not implemented.
- KT-CT-10031: Invalid party filter.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query contracts
Arguments
| Name | Description |
|---|---|
|
Filters to apply when querying contracts. At least one filter must be provided. |
Query
query Contracts($filters: ContractFiltersInput!) {
contracts(filters: $filters) {
cancelledAt
identifier
lifecycle {
...ContractVersionFragment
}
notes {
...ContractNoteTypeFragment
}
party {
... on AccountType {
...AccountTypeFragment
}
... on BusinessType {
...BusinessTypeFragment
}
}
rescindedAt
signedAt
status
subject {
...AccountTypeFragment
}
terms {
...TermInterfaceFragment
}
title
validFrom
validTo
}
}
Variables
{
"filters": ContractFiltersInput
}
Response
{
"data": {
"contracts": [
{
"cancelledAt": "1987-05-29T18:01:58.627422+00:00",
"identifier": "48310208",
"lifecycle": ContractVersion,
"notes": [ContractNoteType],
"party": AccountType,
"rescindedAt": "2024-11-27T13:06:02.736513+00:00",
"signedAt": "1976-03-23T00:35:18.130672+00:00",
"status": "REVOKED",
"subject": [AccountType],
"terms": TermInterface,
"title": "well-reach-laugh-line-little",
"validFrom": "1970-11-12T02:35:14.299300+00:00",
"validTo": "1984-08-16T17:08:20.147241+00:00"
}
]
}
}
contributionSchemes
Type: [ContributionSchemeType]
URL: https://api.octopus.energy/v1/graphql/
Get contribution schemes.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query ContributionSchemes {
contributionSchemes {
acceptingContributions
code
displayName
id
taxable
}
}
Response
{
"data": {
"contributionSchemes": [
{
"acceptingContributions": true,
"code": "else-doctor-at-family-small",
"displayName": "participant-early-top-market-tend",
"id": "78433335",
"taxable": true
}
]
}
}
controllerEuids
Type: [String]
URL: https://api.octopus.energy/v1/graphql/
Heat pump controller EUIDs associated with an account.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'controllerEuids' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Arguments
| Name | Description |
|---|---|
|
Query
query ControllerEuids($accountNumber: String) {
controllerEuids(accountNumber: $accountNumber)
}
Variables
{
"accountNumber": "A-29ACB016"
}
Response
{
"data": {
"controllerEuids": "line-measure-machine-better-number"
}
}
costOfCharge
Type: [CostOfChargeType]
URL: https://api.octopus.energy/v1/graphql/
Aggregated cost of charge for an EV device.
Query Complexity: 1
Possible Errors:
- KT-CT-4326: Could not get consumption cost data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
Deprecated
The 'costOfCharge' field is deprecated.
Use `cost` field on `SmartFlexChargingSession` instead.
- Marked as deprecated on 2025-05-13.
- Scheduled for removal on or after 2026-01-16.
You can read more about this deprecation on:
https://announcements.kraken.tech/announcements/public/605/
Arguments
| Name | Description |
|---|---|
|
|
|
Frequency by day, week, month or year. |
|
The date up to which data should be relative to. |
|
The start date of the results required. Overrides report date (end date) if provided. |
Query
query CostOfCharge(
$accountNumber: String!,
$frequency: DataFrequency!,
$startDate: Date
) {
costOfCharge(
accountNumber: $accountNumber,
frequency: $frequency,
startDate: $startDate
) {
costOfChargeId
isSmartCharge
krakenflexDeviceId
reportDate
totalConsumption
totalCostExclTax
totalCostInclTax
}
}
Variables
{
"accountNumber": "A-F46A5259",
"frequency": "DAILY",
"startDate": "2009-04-15"
}
Response
{
"data": {
"costOfCharge": [
{
"costOfChargeId": "54059747",
"isSmartCharge": true,
"krakenflexDeviceId": "82597499",
"reportDate": "1974-05-13",
"totalConsumption": 852.11,
"totalCostExclTax": 230.4,
"totalCostInclTax": 417.89
}
]
}
}
costOfUsage
Type: CostOfUsageType
URL: https://api.octopus.energy/v1/graphql/
Cost of usage recorded by the meter.
Query Complexity: 4
Possible Errors:
- KT-GB-3810: Unable to get cost of usage.
- KT-GB-4011: No SMETS consumption found.
- KT-GB-6312: Unable to query unit rates.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'costOfUsage' field is deprecated.
Please measurements statistics node instead.
- Marked as deprecated on 2024-09-02.
- Scheduled for removal on or after 2024-12-01.
Arguments
| Name | Description |
|---|---|
|
Account number. |
|
The energy type, i.e. ELECTRICITY or GAS. |
|
Aggregate cost according to this grouping. |
|
The electricity or gas meter ID. |
|
Datetime the data should be queried from. |
|
Timezone to use for grouping. |
Query
query CostOfUsage(
$accountNumber: String,
$fuelType: FuelType,
$grouping: ConsumptionGroupings!,
$meterId: String,
$startAt: DateTime,
$timezone: String
) {
costOfUsage(
accountNumber: $accountNumber,
fuelType: $fuelType,
grouping: $grouping,
meterId: $meterId,
startAt: $startAt,
timezone: $timezone
) {
costEnabled
details {
...CostOfUsageConnectionTypeConnectionFragment
}
direction
}
}
Variables
{
"accountNumber": "A-B076AE71",
"fuelType": "ELECTRICITY",
"grouping": "QUARTER_HOUR",
"meterId": "75385463",
"startAt": "1994-04-24T00:53:32.588116+00:00",
"timezone": "response-century-reach-finish-measure"
}
Response
{
"data": {
"costOfUsage": {
"costEnabled": true,
"details": CostOfUsageConnectionTypeConnection,
"direction": "letter-consider-reason-begin-fire"
}
}
}
customerAsset
Type: CustomerAssetType
URL: https://api.octopus.energy/v1/graphql/
Get customer asset by ID.
Query Complexity: 2
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query customer assets
Arguments
| Name | Description |
|---|---|
|
Customer asset ID. |
Query
query CustomerAsset($customerAssetId: String!) {
customerAsset(customerAssetId: $customerAssetId) {
accountNumber
activeFrom
activeTo
id
name
physicalId
type
}
}
Variables
{
"customerAssetId": "77876414"
}
Response
{
"data": {
"customerAsset": {
"accountNumber": "A-AC185135",
"activeFrom": "2023-08-28T02:52:38.760533+00:00",
"activeTo": "2026-01-17T05:22:23.877031+00:00",
"id": "39105431",
"name": "must-send-break-position-visit",
"physicalId": "34793590",
"type": "rich-story-record-science-production"
}
}
}
customerFeedbackForms
Type: CustomerFeedbackFormConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Returns all active customer feedback forms for the account's brand.
Query Complexity: 1
Possible Errors:
- KT-CT-5515: Unable to retrieve feedback forms.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can submit customer feedback
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
|
|
|
|
Feedback sources currently supported. |
|
|
|
Query
query CustomerFeedbackForms(
$accountNumber: String!,
$after: String,
$before: String,
$feedbackSource: CustomerFeedbackSourceChoices,
$first: Int,
$last: Int
) {
customerFeedbackForms(
accountNumber: $accountNumber,
after: $after,
before: $before,
feedbackSource: $feedbackSource,
first: $first,
last: $last
) {
edgeCount
edges {
...CustomerFeedbackFormConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-A1ABCA32",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"feedbackSource": "FEEDBACK_SOURCE_PHONE_CALL_FOLLOW_UP",
"first": 10,
"last": 10
}
Response
{
"data": {
"customerFeedbackForms": {
"edgeCount": 85,
"edges": [CustomerFeedbackFormConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 3
}
}
}
customerFlexibilityCampaignEvents
Type: CFCampaignEventConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Retrieve Customer Flexibility Campaign Events by the Campaign slug, with customer enrollment info.
Query Complexity: 3
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-12201: Campaign not found.
- KT-CT-12202: Supply point not found.
- KT-CT-12203: Market supply point not supported.
- KT-CT-12204: Market supply point is not associated with the account.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number to check event enrollment for. |
|
|
|
|
|
The slug of the campaign to which the event belongs. |
|
|
|
|
|
The supply point identifier to check event enrollment for. |
Query
query CustomerFlexibilityCampaignEvents(
$accountNumber: String!,
$after: String,
$before: String,
$campaignSlug: String!,
$first: Int,
$last: Int,
$supplyPointIdentifier: String!
) {
customerFlexibilityCampaignEvents(
accountNumber: $accountNumber,
after: $after,
before: $before,
campaignSlug: $campaignSlug,
first: $first,
last: $last,
supplyPointIdentifier: $supplyPointIdentifier
) {
edgeCount
edges {
...CFCampaignEventConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-04E3835A",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"campaignSlug": "population-me-pay-line-nature",
"first": 10,
"last": 10,
"supplyPointIdentifier": "64791815"
}
Response
{
"data": {
"customerFlexibilityCampaignEvents": {
"edgeCount": 47,
"edges": [CFCampaignEventConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 33
}
}
}
dashboardScreen
Type: Dashboard
URL: https://api.octopus.energy/v1/graphql/
Get a dashboard screen to render in the form of a json list of sections containing cards or grouped cards each with an order attribute.
Query Complexity: 1
Possible Errors:
- KT-CT-3820: Received both ledger ID and number.
- KT-CT-8001: No backend screen available.
- KT-CT-8005: Backend screen does not support parameters.
- KT-CT-8006: Error applying parameters to backend screen.
- KT-CT-8008: Incorrect or missing data necessary to build the screen.
- KT-CT-8009: Error translating screen content.
- KT-CT-8010: Invalid step ID.
- KT-CT-8011: Cannot rewind past a previous irreversible step.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number of the user. |
|
The ID of the dashboard type screen to return. |
|
The ledger id associated to the account. |
|
The ledger number associated to the account. |
|
The maximum version of dahshboard type screens supported by the client. |
|
List of key-value pairs (strings) to pass as parameters to the screen. |
|
The property id associated to the account. |
Query
query DashboardScreen(
$accountNumber: String!,
$dashboardId: ID!,
$ledgerNumber: String,
$maxVersionSupported: Int!,
$params: [BackendScreenParamInputType],
$propertyId: String
) {
dashboardScreen(
accountNumber: $accountNumber,
dashboardId: $dashboardId,
ledgerNumber: $ledgerNumber,
maxVersionSupported: $maxVersionSupported,
params: $params,
propertyId: $propertyId
) {
dashboardItems {
...SectionTypeFragment
}
id
serialisedDashboardItems
typename
}
}
Variables
{
"accountNumber": "A-D3A99825",
"dashboardId": "71912486",
"ledgerNumber": "require-kind-represent-soon-admit",
"maxVersionSupported": 59,
"params": BackendScreenParamInputType,
"propertyId": "82797811"
}
Response
{
"data": {
"dashboardScreen": {
"dashboardItems": [SectionType],
"id": "85974437",
"serialisedDashboardItems": "game-conference-view-edge-radio",
"typename": "use-time-stop-baby-security"
}
}
}
defaultElectricJuicePaymentInstruction
Type: DefaultElectricJuicePaymentInstructionType
URL: https://api.octopus.energy/v1/graphql/
Get the default payment instruction for the account's Electric Juice Network ledger.
Query Complexity: 1
Possible Errors:
- KT-GB-6111: Invalid/No payment instruction found for the given account.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'defaultElectricJuicePaymentInstruction' field is deprecated.
Legacy Market
- Marked as deprecated on 2025-08-04.
- Scheduled for removal on or after 2025-09-05.
Arguments
| Name | Description |
|---|---|
|
The account number. |
Query
query DefaultElectricJuicePaymentInstruction($accountNumber: String!) {
defaultElectricJuicePaymentInstruction(accountNumber: $accountNumber) {
cardExpiryMonth
cardExpiryYear
cardNumber
cardPaymentNetwork
cardType
id
instructionType
validFrom
vendor
}
}
Variables
{
"accountNumber": "A-61F63829"
}
Response
{
"data": {
"defaultElectricJuicePaymentInstruction": {
"cardExpiryMonth": 22,
"cardExpiryYear": 77,
"cardNumber": "nothing-also-company-however-bag",
"cardPaymentNetwork": "medical-its-his-teach-so",
"cardType": "least-sea-certain-nation-both",
"id": "84209566",
"instructionType": "control-challenge-seven-sign-ready",
"validFrom": "1992-08-10T19:13:54.042640+00:00",
"vendor": "production-speech-whole-report-two"
}
}
}
defaultPaymentInstruction
Type: PaymentInstructionType
URL: https://api.octopus.energy/v1/graphql/
Get the default payment instruction for the account's main ledger.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'defaultPaymentInstruction' field is deprecated.
Please use 'usablePaymentInstructions' on the Ledger type to get all usable instructions, or 'paymentPreferenceAtTime' on the Ledger type to get a specific one. Both require explicitly requesting a ledger.
- Marked as deprecated on 2026-01-28.
- Scheduled for removal on or after 2026-07-28.
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
Provide an option to get either a CARD or DIRECT_DEBIT instruction. |
Query
query DefaultPaymentInstruction(
$accountNumber: String!,
$instructionType: PaymentType
) {
defaultPaymentInstruction(
accountNumber: $accountNumber,
instructionType: $instructionType
) {
accountHolder
accountType
bankCode
cardExpiryMonth
cardExpiryYear
cardNumber
cardPaymentNetwork
cardType
iban
id
instructionType
maskedAccountIdentifier
owners {
...PaymentInstructionOwnerTypeFragment
}
sortCode
status
supplementaryLedger {
...SupplementaryLedgerTypeFragment
}
validFrom
vendor
}
}
Variables
{
"accountNumber": "A-BCE9D1D6",
"instructionType": "BPAY"
}
Response
{
"data": {
"defaultPaymentInstruction": {
"accountHolder": "together-model-low-deep-right",
"accountType": "part-system-special-under-fight",
"bankCode": "there-majority-southern-manage-Republican",
"cardExpiryMonth": 51,
"cardExpiryYear": 52,
"cardNumber": "sure-wind-its-pretty-federal",
"cardPaymentNetwork": "federal-think-our-medical-price",
"cardType": "choose-environmental-set-into-camera",
"iban": "imagine-cold-charge-natural-thus",
"id": "89093046",
"instructionType": "important-in-grow-movie-benefit",
"maskedAccountIdentifier": "40877093",
"owners": [PaymentInstructionOwnerType],
"sortCode": "book-believe-body-sense-operation",
"status": "physical-better-adult-fall-democratic",
"supplementaryLedger": SupplementaryLedgerType,
"validFrom": "2019-02-01T23:27:04.103990+00:00",
"vendor": "lose-individual-training-prepare-others"
}
}
}
defaultRawScore
Type: Int
URL: https://api.octopus.energy/v1/graphql/
Get default raw score for a customer feedback form.
Query Complexity: 1
Possible Errors:
- KT-CT-5513: Invalid data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can submit customer feedback
Arguments
| Name | Description |
|---|---|
|
Query
query DefaultRawScore($formId: Int!) {
defaultRawScore(formId: $formId)
}
Variables
{
"formId": 10905760
}
Response
{
"data": {
"defaultRawScore": 29
}
}
depositAgreements
Type: [DepositAgreementOutput]
URL: https://api.octopus.energy/v1/graphql/
Get deposit agreements for a given account.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can use deposit system
Arguments
| Name | Description |
|---|---|
|
Query
query DepositAgreements($accountNumber: String!) {
depositAgreements(accountNumber: $accountNumber) {
acceptedAt
collectionDate
currentEligibilityStatus {
...CurrentEligibilityStatusOutputFragment
}
depositAmount
depositKey
dueDate
fulfilledAt
returnStrategy
}
}
Variables
{
"accountNumber": "A-4EA93A89"
}
Response
{
"data": {
"depositAgreements": [
{
"acceptedAt": "2025-06-11T10:45:29.035320+00:00",
"collectionDate": "2020-01-27",
"currentEligibilityStatus": CurrentEligibilityStatusOutput,
"depositAmount": 72,
"depositKey": "instead-although-character-a-agent",
"dueDate": "1986-06-24",
"fulfilledAt": "2018-12-23T05:14:44.445261+00:00",
"returnStrategy": "her-run-where-admit-strong"
}
]
}
}
devices
Type: [SmartFlexDeviceInterface!]
URL: https://api.octopus.energy/v1/graphql/
A list of devices registered to an account.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query devices
Arguments
| Name | Description |
|---|---|
|
The account number, e.g. A-12345678. |
|
Only list the device with this ID. |
|
Only list the device with this integration device ID. |
|
Only list devices registered to this property. |
Query
query Devices(
$accountNumber: String!,
$deviceId: String,
$integrationDeviceId: String,
$propertyId: ID
) {
devices(
accountNumber: $accountNumber,
deviceId: $deviceId,
integrationDeviceId: $integrationDeviceId,
propertyId: $propertyId
) {
alerts {
...SmartFlexDeviceAlertInterfaceFragment
}
deviceType
id
integrationDeviceId
name
onboardingWizard {
...SmartFlexOnboardingWizardFragment
}
preferences {
...SmartFlexDevicePreferencesInterfaceFragment
}
preferenceSetting {
...FlexDevicePreferenceSettingInterfaceFragment
}
propertyId
provider
reAuthenticationState {
...DeviceReAuthenticationInterfaceFragment
}
status {
...SmartFlexDeviceStatusInterfaceFragment
}
}
}
Variables
{
"accountNumber": "A-6641ADC5",
"deviceId": "63464191",
"integrationDeviceId": "48558506",
"propertyId": "31724498"
}
Response
{
"data": {
"devices": [
{
"alerts": SmartFlexDeviceAlertInterface,
"deviceType": "BATTERIES",
"id": "22957786",
"integrationDeviceId": "85521136",
"name": "property-people-too-senior-foreign",
"onboardingWizard": SmartFlexOnboardingWizard,
"preferences": SmartFlexDevicePreferencesInterface,
"preferenceSetting": FlexDevicePreferenceSettingInterface,
"propertyId": "98521742",
"provider": "BYD",
"reAuthenticationState": DeviceReAuthenticationInterface,
"status": SmartFlexDeviceStatusInterface
}
]
}
}
domesticAccountReferralRewardScheme
Type: ReferralSchemeType
URL: https://api.octopus.energy/v1/graphql/
Return a domestic referral reward scheme for the given account referral code.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Friend referral code. |
Query
query DomesticAccountReferralRewardScheme($code: String!) {
domesticAccountReferralRewardScheme(code: $code) {
canBeReferred
code
combinedRewardAmount
isUsageAtCapacity
loyaltyPointsBonus
maxRecurrence
referralDisplayUrl
referralUrl
referredRewardAmount
referrerGivenName
referrerRewardAmount
schemeType
}
}
Variables
{
"code": "dog-cover-international-chair-public"
}
Response
{
"data": {
"domesticAccountReferralRewardScheme": {
"canBeReferred": true,
"code": "age-government-every-security-decide",
"combinedRewardAmount": 62,
"isUsageAtCapacity": true,
"loyaltyPointsBonus": 10,
"maxRecurrence": 69,
"referralDisplayUrl": "friend-age-other-project-report",
"referralUrl": "tree-west-first-southern-light",
"referredRewardAmount": 95,
"referrerGivenName": "Barry",
"referrerRewardAmount": 25,
"schemeType": "never-popular-school-must-single"
}
}
}
domesticJoiningRewardScheme
Type: ReferralSchemeType
URL: https://api.octopus.energy/v1/graphql/
Return a joining reward scheme with the given code, if it's active. A joining reward can be a signup reward or a promotional reward.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Reward code for the scheme. |
Query
query DomesticJoiningRewardScheme($code: String!) {
domesticJoiningRewardScheme(code: $code) {
canBeReferred
code
combinedRewardAmount
isUsageAtCapacity
loyaltyPointsBonus
maxRecurrence
referralDisplayUrl
referralUrl
referredRewardAmount
referrerGivenName
referrerRewardAmount
schemeType
}
}
Variables
{
"code": "all-thought-civil-phone-early"
}
Response
{
"data": {
"domesticJoiningRewardScheme": {
"canBeReferred": true,
"code": "by-ball-month-your-life",
"combinedRewardAmount": 64,
"isUsageAtCapacity": true,
"loyaltyPointsBonus": 86,
"maxRecurrence": 22,
"referralDisplayUrl": "leader-stock-let-toward-occur",
"referralUrl": "piece-laugh-begin-nature-wind",
"referredRewardAmount": 32,
"referrerGivenName": "Monique",
"referrerRewardAmount": 14,
"schemeType": "majority-reason-character-sea-image"
}
}
}
domesticSignupRewardScheme
Type: ReferralSchemeType
URL: https://api.octopus.energy/v1/graphql/
Return a signup referral reward scheme with the given code, if it's active.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Reward code for the scheme. |
Query
query DomesticSignupRewardScheme($code: String!) {
domesticSignupRewardScheme(code: $code) {
canBeReferred
code
combinedRewardAmount
isUsageAtCapacity
loyaltyPointsBonus
maxRecurrence
referralDisplayUrl
referralUrl
referredRewardAmount
referrerGivenName
referrerRewardAmount
schemeType
}
}
Variables
{
"code": "case-attention-provide-boy-serve"
}
Response
{
"data": {
"domesticSignupRewardScheme": {
"canBeReferred": true,
"code": "floor-cultural-statement-news-force",
"combinedRewardAmount": 9,
"isUsageAtCapacity": true,
"loyaltyPointsBonus": 9,
"maxRecurrence": 39,
"referralDisplayUrl": "party-risk-director-already-story",
"referralUrl": "real-no-case-something-statement",
"referredRewardAmount": 40,
"referrerGivenName": "Tammy",
"referrerRewardAmount": 4,
"schemeType": "life-bad-number-prevent-job"
}
}
}
earliestPossibleDirectDebitPaymentDate
Type: EarliestPossibleDirectDebitPaymentDate
URL: https://api.octopus.energy/v1/graphql/
Earliest possible payment date from today for which the first direct debit payment can be made.
Query Complexity: 1
Possible Errors:
- KT-GB-3914: Unable to get earliest ssd payment date.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query EarliestPossibleDirectDebitPaymentDate {
earliestPossibleDirectDebitPaymentDate {
earliestPossibleDirectDebitPaymentDate
}
}
Response
{
"data": {
"earliestPossibleDirectDebitPaymentDate": {
"earliestPossibleDirectDebitPaymentDate": "1978-05-31"
}
}
}
electricityAgreement
Type: AgreementInterface
URL: https://api.octopus.energy/v1/graphql/
Get an electricity agreement.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query agreements
Arguments
| Name | Description |
|---|---|
|
ID of the electricity agreement. |
Query
query ElectricityAgreement($id: ID!) {
electricityAgreement(id: $id) {
agreedFrom
agreedTo
id
isRevoked
ratesAgreedAt
rescissionDeadlineAt
validFrom
validTo
}
}
Variables
{
"id": "55628080"
}
Response
{
"data": {
"electricityAgreement": {
"agreedFrom": "2002-02-22T22:03:33.164247+00:00",
"agreedTo": "2004-02-29T19:10:57.895160+00:00",
"id": 19995907,
"isRevoked": true,
"ratesAgreedAt": "1973-10-04T02:16:28.570735+00:00",
"rescissionDeadlineAt": "2004-08-08T13:25:55.600707+00:00",
"validFrom": "2003-06-02T18:27:12.274150+00:00",
"validTo": "2012-03-13T06:16:12.893801+00:00"
}
}
}
electricityMeterpoint
Type: ElectricMeterTechnicalDetails
URL: https://api.octopus.energy/v1/graphql/
Search for the meterpoint with given MPAN using ECOES switching API.
Query Complexity: 6
Possible Errors:
- KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6634: The provided MPAN is not valid.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The MPAN of the meterpoint. |
Query
query ElectricityMeterpoint($mpan: String!) {
electricityMeterpoint(mpan: $mpan) {
annualConsumption
annualConsumptionEfd
annualConsumptionQualityIndicator
assignedMdrEfd
assignedMdrMpid
connectionType
connectionTypeEfd
connectionTypeEtd
consumerType
cssSupplierMpid
cssSupplyStartDate
customerDirectContractDsDipId
customerDirectContractDsExists
customerDirectContractDsMpid
customerDirectContractMsDipId
customerDirectContractMsExists
customerDirectContractMsMpid
dataAggregatorEfd
dataAggregatorMpid
dataCollectorEfd
dataCollectorMpid
dataServiceDipId
dataServiceEfd
dataServiceMpid
dccServiceFlag
dccServiceFlagEfd
disconnectionEfd
distributorDipId
distributorMpid
domesticPremisesIndicator
duosTariffId
duosTariffIdEfd
energisationStatus
energisationStatusEfd
energyDirection
energyDirectionEfd
energyDirectionEtd
greenDealInEffect
gspGroupEfd
gspGroupId
ihdStatus
ihdStatusEfd
lineLossFactor
lineLossFactorEfd
marketSegmentIndicator
marketSegmentIndicatorEfd
measurementClass
measurementClassEfd
meteredIndicator
meteredIndicatorEfd
meteredIndicatorEtd
meteringServiceDipId
meteringServiceEfd
meteringServiceEtd
meteringServiceMpid
meterOperatorEfd
meterOperatorMpid
meters {
...ElectricMeterTechnicalSubDetailsFragment
}
meterTimeswitchClass
meterTimeswitchClassEfd
mhhsIndicator
mhhsIndicatorEfd
mpan
profileClass
profileClassEfd
relationshipStatusIndicator
rmpState
rmpStateEfd
smetsVersion
smsoEfd
smsoMpid
standardSettlementConfiguration
standardSettlementConfigurationEfd
supplierDipId
supplierEfd
supplierMpid
tradingStatus
tradingStatusEfd
}
}
Variables
{
"mpan": "place-by-cover-various-word"
}
Response
{
"data": {
"electricityMeterpoint": {
"annualConsumption": "1.0",
"annualConsumptionEfd": "2026-04-12",
"annualConsumptionQualityIndicator": "fill-blue-cup-no-become",
"assignedMdrEfd": "1986-09-08",
"assignedMdrMpid": "69356352",
"connectionType": "method-recently-others-go-year",
"connectionTypeEfd": "1999-07-09",
"connectionTypeEtd": "2005-02-19",
"consumerType": "interesting-still-past-sound-floor",
"cssSupplierMpid": "79297380",
"cssSupplyStartDate": "1998-06-24",
"customerDirectContractDsDipId": "82252451",
"customerDirectContractDsExists": true,
"customerDirectContractDsMpid": "20891697",
"customerDirectContractMsDipId": "10958852",
"customerDirectContractMsExists": true,
"customerDirectContractMsMpid": "27331994",
"dataAggregatorEfd": "1979-10-10",
"dataAggregatorMpid": "99853760",
"dataCollectorEfd": "1989-08-16",
"dataCollectorMpid": "32049942",
"dataServiceDipId": "36337079",
"dataServiceEfd": "1991-02-06",
"dataServiceMpid": "43741963",
"dccServiceFlag": "general-report-west-conference-grow",
"dccServiceFlagEfd": "2015-06-04",
"disconnectionEfd": "2006-05-25",
"distributorDipId": "64318339",
"distributorMpid": "93952153",
"domesticPremisesIndicator": true,
"duosTariffId": "61528081",
"duosTariffIdEfd": "1999-10-03",
"energisationStatus": "put-east-down-really-camera",
"energisationStatusEfd": "1991-10-22",
"energyDirection": "build-ask-player-hope-yet",
"energyDirectionEfd": "2004-09-07",
"energyDirectionEtd": "2010-08-12",
"greenDealInEffect": "community-sit-plant-tell-central",
"gspGroupEfd": "2009-06-28",
"gspGroupId": "20537627",
"ihdStatus": "serve-describe-receive-name-company",
"ihdStatusEfd": "2010-07-31",
"lineLossFactor": "address-yourself-if-expert-enough",
"lineLossFactorEfd": "2009-08-19",
"marketSegmentIndicator": "reduce-budget-cup-officer-tough",
"marketSegmentIndicatorEfd": "1999-12-13",
"measurementClass": "hold-radio-read-at-modern",
"measurementClassEfd": "1988-03-18",
"meteredIndicator": true,
"meteredIndicatorEfd": "2021-04-16",
"meteredIndicatorEtd": "2024-04-20",
"meteringServiceDipId": "98080891",
"meteringServiceEfd": "2008-10-24",
"meteringServiceEtd": "1990-05-12",
"meteringServiceMpid": "59946247",
"meterOperatorEfd": "2012-01-28",
"meterOperatorMpid": "99880755",
"meters": [ElectricMeterTechnicalSubDetails],
"meterTimeswitchClass": 34,
"meterTimeswitchClassEfd": "2003-05-02",
"mhhsIndicator": "car-listen-memory-staff-just",
"mhhsIndicatorEfd": "1973-03-25",
"mpan": "bad-news-kid-sometimes-more",
"profileClass": 39,
"profileClassEfd": "2018-02-18",
"relationshipStatusIndicator": "scientist-hot-talk-imagine-class",
"rmpState": "material-score-laugh-four-plan",
"rmpStateEfd": "1993-11-22",
"smetsVersion": "community-whom-anything-but-understand",
"smsoEfd": "1977-04-14",
"smsoMpid": "33161451",
"standardSettlementConfiguration": "detail-newspaper-development-government-hard",
"standardSettlementConfigurationEfd": "2006-07-09",
"supplierDipId": "47388207",
"supplierEfd": "2023-04-25",
"supplierMpid": "85270012",
"tradingStatus": "month-able-result-firm-too",
"tradingStatusEfd": "1972-07-14"
}
}
}
electricityMeterPointDetails
Type: ElectricityMeterPointDetails
URL: https://api.octopus.energy/v1/graphql/
Search for the meter point details with given MPAN using ECOES switching API.
Query Complexity: 6
Possible Errors:
- KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6634: The provided MPAN is not valid.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The MPAN of the meter point. |
Query
query ElectricityMeterPointDetails($mpan: String!) {
electricityMeterPointDetails(mpan: $mpan) {
meterPoint {
...ElectricityMeterPointTypeFragment
}
networkRates {
...ElectricityNetworkRatesFragment
}
relAddress {
...UniqueRELAddressTypeFragment
}
technicalDetails {
...ElectricMeterTechnicalDetailsFragment
}
}
}
Variables
{
"mpan": "control-however-job-television-sea"
}
Response
{
"data": {
"electricityMeterPointDetails": {
"meterPoint": ElectricityMeterPointType,
"networkRates": ElectricityNetworkRates,
"relAddress": UniqueRELAddressType,
"technicalDetails": ElectricMeterTechnicalDetails
}
}
}
electricityMeterReadings
Type: ElectricityMeterReadingConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Fetch electricity meter readings for a given account and meter
This field is a connection type. Connections are used to implement cursor based pagination.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Only fetch meter readings made since this date |
|
Only fetch meter readings made until this date |
Query
query ElectricityMeterReadings(
$accountNumber: String!,
$after: String,
$before: String,
$eventTypes: [MeterReadingEventType],
$first: Int,
$last: Int,
$meterId: String!,
$readFrom: DateTime,
$readTo: DateTime
) {
electricityMeterReadings(
accountNumber: $accountNumber,
after: $after,
before: $before,
eventTypes: $eventTypes,
first: $first,
last: $last,
meterId: $meterId,
readFrom: $readFrom,
readTo: $readTo
) {
edgeCount
edges {
...ElectricityMeterReadingConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-3D6B4B2D",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"eventTypes": "CUSTOMER",
"first": 10,
"last": 10,
"meterId": "93422245",
"readFrom": "1992-01-25T10:02:23.108264+00:00",
"readTo": "1975-11-11T05:37:39.801887+00:00"
}
Response
{
"data": {
"electricityMeterReadings": {
"edgeCount": 21,
"edges": [ElectricityMeterReadingConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 78
}
}
}
electricityPrepayLedgers
Type: PrepayLedgersType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-GB-6212: Meter does not exist.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query ElectricityPrepayLedgers(
$accountNumber: String!,
$mpan: String!,
$serialNumber: String!
) {
electricityPrepayLedgers(
accountNumber: $accountNumber,
mpan: $mpan,
serialNumber: $serialNumber
) {
creditLedger {
...SupplementaryLedgerTypeFragment
}
debtLedger {
...SupplementaryLedgerTypeFragment
}
paymentLedger {
...PrepayPaymentLedgerTypeFragment
}
}
}
Variables
{
"accountNumber": "A-0919C938",
"mpan": "station-trade-government-at-treatment",
"serialNumber": "clearly-response-baby-deep-return"
}
Response
{
"data": {
"electricityPrepayLedgers": {
"creditLedger": SupplementaryLedgerType,
"debtLedger": SupplementaryLedgerType,
"paymentLedger": PrepayPaymentLedgerType
}
}
}
electricVehicles
Type: [ElectricVehicleType]
URL: https://api.octopus.energy/v1/graphql/
All electric vehicle types and their details.
Query Complexity: 1
Possible Errors:
- KT-CT-4343: Unable to fetch electric vehicles list for make.
- KT-CT-4344: Make is not supported by provider.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Deprecated
The 'electricVehicles' field is deprecated.
Please use 'flexSupportedDevices' instead.
- Marked as deprecated on 2026-04-15.
- Scheduled for removal on or after 2026-10-15.
Arguments
| Name | Description |
|---|---|
|
Only return vehicles that are currently integrated. |
|
Only return vehicle types for the specified make. |
|
Only return vehicle types supported by the specified provider, e.g. Tesla. |
Query
query ElectricVehicles(
$isIntegrationLive: Boolean,
$make: String,
$supportedProvider: ProviderChoices
) {
electricVehicles(
isIntegrationLive: $isIntegrationLive,
make: $make,
supportedProvider: $supportedProvider
) {
make
models {
...ElectricVehicleModelTypeFragment
}
}
}
Variables
{
"isIntegrationLive": true,
"make": "cover-within-over-chance-away",
"supportedProvider": "BYD"
}
Response
{
"data": {
"electricVehicles": [
{
"make": "cause-manager-have-little-difficult",
"models": [ElectricVehicleModelType]
}
]
}
}
eligibilityToJoinLoyaltyPointsProgram
Type: LoyaltyPointsProgramEligibilityType
URL: https://api.octopus.energy/v1/graphql/
Check if an account is eligible to join the loyalty points program.
Query Complexity: 1
Possible Errors:
- KT-CT-9202: Loyalty Points adapter not configured.
- KT-CT-9218: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query loyalty enrollment eligibility
Arguments
| Name | Description |
|---|---|
Query
query EligibilityToJoinLoyaltyPointsProgram($input: LoyaltyPointsProgramEligibilityInput!) {
eligibilityToJoinLoyaltyPointsProgram(input: $input) {
isEligible
primaryIneligibilityReason
}
}
Variables
{
"input": LoyaltyPointsProgramEligibilityInput
}
Response
{
"data": {
"eligibilityToJoinLoyaltyPointsProgram": {
"isEligible": true,
"primaryIneligibilityReason": "record-clear-I-foot-less"
}
}
}
eligibleDeviceTypes
Type: [KrakenFlexDeviceTypes]
URL: https://api.octopus.energy/v1/graphql/
A list of device types that are eligible for registration.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can view smartflex data
Arguments
| Name | Description |
|---|---|
|
The account number, e.g. A-12345678. |
|
|
Query
query EligibleDeviceTypes(
$accountNumber: String!,
$propertyId: Int
) {
eligibleDeviceTypes(
accountNumber: $accountNumber,
propertyId: $propertyId
)
}
Variables
{
"accountNumber": "A-9B28EDDE",
"propertyId": 56721110
}
Response
{
"data": {
"eligibleDeviceTypes": "BATTERIES"
}
}
embeddedNetwork
Type: EmbeddedNetworkType
URL: https://api.octopus.energy/v1/graphql/
Get details about an embedded network.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query embedded network
Arguments
| Name | Description |
|---|---|
|
Query
query EmbeddedNetwork($id: ID!) {
embeddedNetwork(id: $id) {
embeddedProperties {
...EmbeddedPropertyTypeFragment
}
id
name
}
}
Variables
{
"id": "41305102"
}
Response
{
"data": {
"embeddedNetwork": {
"embeddedProperties": [EmbeddedPropertyType],
"id": "96173157",
"name": "make-soldier-quite-appear-reason"
}
}
}
energyProduct
Type: EnergyProductType
URL: https://api.octopus.energy/v1/graphql/
Get an energy product that matches the given code.
Query Complexity: 1
Possible Errors:
- KT-GB-9514: No available product found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Code for the energy product. |
Query
query EnergyProduct($code: String!) {
energyProduct(code: $code) {
availableFrom
availableTo
code
description
direction
displayName
endsAt
exitFees
exitFeesType
fullName
id
includesEpgReduction
isAvailable
isBusiness
isChargedHalfHourly
isDefault
isDomestic
isFixed
isGreen
isHidden
isOccupier
isPrepay
isUnavailable
isVariable
notes
tags
tariffs {
...EnergyTariffConnectionTypeConnectionFragment
}
term
}
}
Variables
{
"code": "yet-create-manager-social-threat"
}
Response
{
"data": {
"energyProduct": {
"availableFrom": "2019-01-06T01:47:22.124970+00:00",
"availableTo": "1990-12-07T15:04:21.004101+00:00",
"code": "design-middle-environmental-goal-save",
"description": "price-cut-lead-radio-moment",
"direction": "IMPORT",
"displayName": "three-prepare-course-their-rule",
"endsAt": "2011-03-14T21:29:56.348279+00:00",
"exitFees": 69,
"exitFeesType": "control-serve-dinner-answer-attention",
"fullName": "role-bag-manage-American-world",
"id": "57846614",
"includesEpgReduction": true,
"isAvailable": true,
"isBusiness": true,
"isChargedHalfHourly": true,
"isDefault": true,
"isDomestic": true,
"isFixed": true,
"isGreen": true,
"isHidden": true,
"isOccupier": true,
"isPrepay": true,
"isUnavailable": true,
"isVariable": true,
"notes": "machine-once-kitchen-free-trade",
"tags": "may-answer-eight-each-choice",
"tariffs": EnergyTariffConnectionTypeConnection,
"term": 45
}
}
}
energyProducts
Type: EnergyProductConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get all products for a given brand and postcode. The supplied postcode will ensure that there are tariffs available on the product for the GSP.
Query Complexity: 1
Possible Errors:
- KT-GB-9516: We were unable to find any products for this brand.
- KT-GB-9517: We were unable to determine the GSP group ID from the postcode.
- KT-GB-9520: Provided tag codes do not exist.
- KT-GB-9521: Invalid energy product direction.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
Filter for available or unavailable products only. |
|
|
|
Filter by a specific energy brand. |
|
Filter by these brands. |
|
Energy product direction to filter products by. |
|
Exclude products with these tag codes. |
|
Filter by the type of energy product. |
|
|
|
|
|
Postcode to search energy products for. |
|
Filter by specific tags which are attached to the product. |
Query
query EnergyProducts(
$after: String,
$availability: EnergyProductAvailability,
$before: String,
$brand: String,
$brands: [String],
$direction: EnergyProductDirection,
$excludeTags: [String],
$filterBy: [EnergyProductFilters],
$first: Int,
$last: Int,
$postcode: String!,
$tags: [String]
) {
energyProducts(
after: $after,
availability: $availability,
before: $before,
brand: $brand,
brands: $brands,
direction: $direction,
excludeTags: $excludeTags,
filterBy: $filterBy,
first: $first,
last: $last,
postcode: $postcode,
tags: $tags
) {
edgeCount
edges {
...EnergyProductConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"availability": "AVAILABLE",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"brand": "interesting-check-theory-make-lawyer",
"brands": "notice-upon-financial-hit-need",
"direction": "IMPORT",
"excludeTags": "save-concern-behavior-send-boy",
"filterBy": "PREPAY",
"first": 10,
"last": 10,
"postcode": "character-dark-begin-recently-hand",
"tags": "situation-wife-quickly-source-girl"
}
Response
{
"data": {
"energyProducts": {
"edgeCount": 63,
"edges": [EnergyProductConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 97
}
}
}
estimateMeterReadings
Type: MeterReadingEstimationReadingConnection
URL: https://api.octopus.energy/v1/graphql/
Estimated meter readings.
Query Complexity: 3
Possible Errors:
- KT-CT-13605: No Algorithm configuration found for the provided use case configuration.
- KT-CT-6426: No supply point found for identifier provided.
- KT-CT-6427: Missing meter readings.
- KT-CT-6428: Meter Readings invalid.
- KT-CT-6429: Granularity is invalid.
- KT-CT-6430: Multiple metadata found for the provided meter and register combination.
- KT-CT-6431: No metadata found for the provided meter and register combination.
- KT-CT-6432: Extrapolate forward estimation is not configured for this territory.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can estimate meter readings
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
The meter id to perform estimation on. |
|
|
|
|
|
This is the unique identifier used by the market to identify the supply point. |
|
The end of the period estimated. |
|
The start of the period estimated. |
|
The meter's register identifier. |
Query
query EstimateMeterReadings(
$after: String,
$before: String,
$deviceId: ID,
$first: Int,
$last: Int,
$marketIdentifier: ID!,
$periodEnd: DateTime!,
$periodStart: DateTime!,
$registerId: ID
) {
estimateMeterReadings(
after: $after,
before: $before,
deviceId: $deviceId,
first: $first,
last: $last,
marketIdentifier: $marketIdentifier,
periodEnd: $periodEnd,
periodStart: $periodStart,
registerId: $registerId
) {
edgeCount
edges {
...MeterReadingEstimationReadingEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"deviceId": "96246998",
"first": 10,
"last": 10,
"marketIdentifier": "62559987",
"periodEnd": "1985-08-13T19:49:30.308514+00:00",
"periodStart": "2012-10-23T13:24:18.871635+00:00",
"registerId": "27680302"
}
Response
{
"data": {
"estimateMeterReadings": {
"edgeCount": 26,
"edges": [MeterReadingEstimationReadingEdge],
"pageInfo": PageInfo,
"totalCount": 14
}
}
}
extendedAnnualElectricityConsumption
Type: ExtendedElectricityConsumptionType!
URL: https://api.octopus.energy/v1/graphql/
The annual electricity consumption data for an MPAN, breaking down by day and night consumption, if available.
Query Complexity: 5
Possible Errors:
- KT-GB-12401: Invalid MPAN supplied.
- KT-GB-12402: Unable to get estimated consumption.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query annual consumption
Arguments
| Name | Description |
|---|---|
|
The MPAN of the meterpoint to return. |
Query
query ExtendedAnnualElectricityConsumption($mpan: String!) {
extendedAnnualElectricityConsumption(mpan: $mpan) {
eacDay
eacNight
eacStandard
}
}
Variables
{
"mpan": "herself-glass-radio-than-center"
}
Response
{
"data": {
"extendedAnnualElectricityConsumption": {
"eacDay": 141.36,
"eacNight": 946.52,
"eacStandard": 475.37
}
}
}
externalAccountEvents
Type: ExternalAccountEventConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get a list of audit account events, of type external, for a given account.
Query Complexity: 1
Possible Errors:
- KT-CT-7127: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query external account events
Arguments
| Name | Description |
|---|---|
|
Account number to filter by. |
|
|
|
|
|
|
|
Query
query ExternalAccountEvents(
$accountNumber: String!,
$after: String,
$before: String,
$first: Int,
$last: Int
) {
externalAccountEvents(
accountNumber: $accountNumber,
after: $after,
before: $before,
first: $first,
last: $last
) {
edgeCount
edges {
...ExternalAccountEventConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-0BF64869",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10
}
Response
{
"data": {
"externalAccountEvents": {
"edgeCount": 90,
"edges": [ExternalAccountEventConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 100
}
}
}
fanClubStatus
Type: [FanClubStatus]
URL: https://api.octopus.energy/v1/graphql/
Get current status, historic discounts and future projections for a Fan Club source.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
- KT-CT-6622: Unauthorized.
- KT-CT-8102: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
The ID of the property. |
Query
query FanClubStatus(
$accountNumber: String,
$propertyId: Int
) {
fanClubStatus(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
accountNumbers
catchments
current {
...DiscountDataFragment
}
discountSource
forecast {
...DiscountForecastFragment
}
historic {
...DiscountDataFragment
}
location
name
propertyIds
thresholds {
...ThresholdFragment
}
windFarm
}
}
Variables
{
"accountNumber": "A-5F2F71AB",
"propertyId": 31464556
}
Response
{
"data": {
"fanClubStatus": [
{
"accountNumbers": "dark-study-account-movie-operation",
"catchments": "property-place-television-forget-present",
"current": DiscountData,
"discountSource": "add-in-well-improve-until",
"forecast": DiscountForecast,
"historic": [DiscountData],
"location": "figure-buy-foot-kid-minute",
"name": "particular-detail-together-decade-radio",
"propertyIds": 19,
"thresholds": [Threshold],
"windFarm": "tree-eight-word-bit-campaign"
}
]
}
}
fieldSalesVisits
Type: FieldSalesVisitConnectionTypeConnection!
URL: https://api.octopus.energy/v1/graphql/
The history of field sales visits to a specific address.
Query Complexity: 1
Possible Errors:
- KT-GB-1301: The provided postcode is not a UK postcode.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query field sales visits
Deprecated
The 'fieldSalesVisits' field is deprecated.
Please use `appSessions` query instead.
- Marked as deprecated on 2025-08-10.
- Scheduled for removal on or after 2025-10-01.
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
The postcode of the addresses to return. |
Query
query FieldSalesVisits(
$after: String,
$before: String,
$first: Int,
$last: Int,
$postcode: String!
) {
fieldSalesVisits(
after: $after,
before: $before,
first: $first,
last: $last,
postcode: $postcode
) {
edgeCount
edges {
...FieldSalesVisitConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"postcode": "loss-attention-hope-attorney-industry"
}
Response
{
"data": {
"fieldSalesVisits": {
"edgeCount": 31,
"edges": [FieldSalesVisitConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 59
}
}
}
fitInstallations
Type: [InstallationType]
URL: https://api.octopus.energy/v1/graphql/
Get details about FIT installations attached to an account, including any meters and previous readings.
Query Complexity: 1
Possible Errors:
- KT-GB-6811: Account does not exist.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query fit installations
Arguments
| Name | Description |
|---|---|
|
Account to query for FIT installations. |
Query
query FitInstallations($accountNumber: String!) {
fitInstallations(accountNumber: $accountNumber) {
fitId
fitTermsAgreedAt
inspectionAt
meters {
...FitMeterTypeFragment
}
propertyAddress {
...PropertyAddressTypeFragment
}
technologyType
}
}
Variables
{
"accountNumber": "A-6AAC269D"
}
Response
{
"data": {
"fitInstallations": [
{
"fitId": "25286621",
"fitTermsAgreedAt": "2003-07-10T14:05:13.415362+00:00",
"inspectionAt": "1974-03-29T11:54:44.417279+00:00",
"meters": [FitMeterType],
"propertyAddress": PropertyAddressType,
"technologyType": "ANAEROBIC_DIGESTION"
}
]
}
}
fitSchedule
Type: FitScheduleType
URL: https://api.octopus.energy/v1/graphql/
Get details about a FIT schedule attached to an account.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query fit schedules
Arguments
| Name | Description |
|---|---|
|
The number of the account responsible for this FIT schedule. |
|
Unique identifier for the schedule. |
Query
query FitSchedule(
$accountNumber: String!,
$scheduleId: String!
) {
fitSchedule(
accountNumber: $accountNumber,
scheduleId: $scheduleId
) {
acceptedAt
scheduleId
sentAt
temporaryDownloadUrls
}
}
Variables
{
"accountNumber": "A-DBC48A76",
"scheduleId": "19069419"
}
Response
{
"data": {
"fitSchedule": {
"acceptedAt": "1987-04-26T01:02:08.067122+00:00",
"scheduleId": "b80d6b8f-fc01-40be-82e8-d7aa0740d00e",
"sentAt": "1997-03-01T12:08:17.611965+00:00",
"temporaryDownloadUrls": "myself-security-discussion-economy-society"
}
}
}
flexPlannedDispatches
Type: [SmartFlexDispatch]
URL: https://api.octopus.energy/v1/graphql/
All planned device dispatches in time order.
Query Complexity: 3
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4340: Unable to fetch planned dispatches.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can view smartflex data
Rate Limits
| Key | Steps |
|---|---|
User |
['5/m'] |
Arguments
| Name | Description |
|---|---|
|
The SmartFlex device ID to get the planned dispatches for. |
Query
query FlexPlannedDispatches($deviceId: String!) {
flexPlannedDispatches(deviceId: $deviceId) {
end
energyAddedKwh
start
type
}
}
Variables
{
"deviceId": "99778462"
}
Response
{
"data": {
"flexPlannedDispatches": [
{
"end": "1972-06-12T01:32:49.955254+00:00",
"energyAddedKwh": "1.0",
"start": "1971-12-01T05:49:32.622983+00:00",
"type": "SMART"
}
]
}
}
flexSupportedDevices
Type: FlexSupportedDevices
URL: https://api.octopus.energy/v1/graphql/
Devices capable of being registered with SmartFlex.
Query Complexity: 1
Possible Errors:
- KT-CT-4342: One of `deviceType` or `supportedDeviceType` must be provided.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['10/m'] |
Arguments
| Name | Description |
|---|---|
|
The device type to get the supported devices for. Deprecated: use |
|
The device type to get the supported devices for, including charge points. Exactly one of |
Query
query FlexSupportedDevices($supportedDeviceType: FlexSupportedDeviceTypes) {
flexSupportedDevices(supportedDeviceType: $supportedDeviceType) {
deviceType
supportedDeviceType
supportedMakes {
...FlexSupportedMakeFragment
}
}
}
Variables
{
"supportedDeviceType": "CHARGE_POINTS"
}
Response
{
"data": {
"flexSupportedDevices": {
"deviceType": "BATTERIES",
"supportedDeviceType": "CHARGE_POINTS",
"supportedMakes": [FlexSupportedMake]
}
}
}
followOnProduct
Type: FollowOnProductType
URL: https://api.octopus.energy/v1/graphql/
Follow on product.
Query Complexity: 1
Possible Errors:
- KT-GB-9510: At least one agreement ID is required.
- KT-GB-9511: Please, provide either electricity_agreement_id or gas_agreement_id. Both are not accepted.
- KT-GB-9512: No agreement found.
- KT-GB-9513: No follow on product found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
|
Electricity agreement Kraken ID. |
|
Gas agreement Kraken ID. |
|
Query
query FollowOnProduct(
$accountNumber: String!,
$electricityAgreementId: ID,
$gasAgreementId: ID,
$validAt: DateTime!
) {
followOnProduct(
accountNumber: $accountNumber,
electricityAgreementId: $electricityAgreementId,
gasAgreementId: $gasAgreementId,
validAt: $validAt
) {
accountType
activeFrom
activeTo
createdAt
paymentMethod
renewalProducts {
...RenewalProductTypeFragment
}
}
}
Variables
{
"accountNumber": "A-A581FE5C",
"electricityAgreementId": "86710703",
"gasAgreementId": "69022460",
"validAt": "1989-04-23T08:35:57.331621+00:00"
}
Response
{
"data": {
"followOnProduct": {
"accountType": "BUSINESS",
"activeFrom": "1986-12-14T06:56:51.586981+00:00",
"activeTo": "1982-10-23T02:20:30.281675+00:00",
"createdAt": "1994-03-07T13:15:57.135243+00:00",
"paymentMethod": "DIRECT_DEBIT",
"renewalProducts": [RenewalProductType]
}
}
}
fraudMeterPointChecks
Type: FraudMeterPointCheckType
URL: https://api.octopus.energy/v1/graphql/
Check if a given meter point ID is in suspicious meter point IDs list.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The meter point ID. |
Query
query FraudMeterPointChecks($meterPointId: String!) {
fraudMeterPointChecks(meterPointId: $meterPointId) {
isInSuspiciousList
meterPointId
}
}
Variables
{
"meterPointId": "32971752"
}
Response
{
"data": {
"fraudMeterPointChecks": {
"isInSuspiciousList": true,
"meterPointId": "95125864"
}
}
}
fraudRiskLevel
Type: FinancialRiskLevelType
URL: https://api.octopus.energy/v1/graphql/
Check if a given ID and type have a financial risk level.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The type of object the ID represents. |
|
The ID to be checked. |
Query
query FraudRiskLevel(
$identifierType: String!,
$identifierValue: String!
) {
fraudRiskLevel(
identifierType: $identifierType,
identifierValue: $identifierValue
) {
identifierType
identifierValue
isInRiskList
riskLevel
}
}
Variables
{
"identifierType": "lose-could-daughter-none-wall",
"identifierValue": "paper-chance-whether-society-finish"
}
Response
{
"data": {
"fraudRiskLevel": {
"identifierType": "site-cover-kitchen-one-door",
"identifierValue": "22310459",
"isInRiskList": true,
"riskLevel": "1.0"
}
}
}
gasAgreement
Type: AgreementInterface
URL: https://api.octopus.energy/v1/graphql/
Get a gas agreement.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query agreements
Arguments
| Name | Description |
|---|---|
|
ID of the gas agreement. |
Query
query GasAgreement($id: ID!) {
gasAgreement(id: $id) {
agreedFrom
agreedTo
id
isRevoked
ratesAgreedAt
rescissionDeadlineAt
validFrom
validTo
}
}
Variables
{
"id": "38899508"
}
Response
{
"data": {
"gasAgreement": {
"agreedFrom": "2022-04-28T06:52:28.446868+00:00",
"agreedTo": "2019-09-02T19:42:04.712465+00:00",
"id": 67448737,
"isRevoked": true,
"ratesAgreedAt": "1984-09-13T13:04:58.834484+00:00",
"rescissionDeadlineAt": "1984-05-26T01:25:06.476492+00:00",
"validFrom": "1985-04-27T22:10:49.570226+00:00",
"validTo": "1989-04-26T14:49:26.154866+00:00"
}
}
}
gasMeterpoint
Type: GasMeterTechnicalDetails
URL: https://api.octopus.energy/v1/graphql/
Search for the meterpoint with given MPRN using Xoserve switching API.
Query Complexity: 6
Possible Errors:
- KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6635: The provided MPRN is not valid.
- KT-GB-6636: The provided MPRN is linked to an extinct meterpoint.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The MPRN of the meterpoint. |
Query
query GasMeterpoint($mprn: String!) {
gasMeterpoint(mprn: $mprn) {
currentSupplierId
currentSupplierRegEffectiveDate
dmq
gasTransportId
ldzId
marketSectorCode
meterCapacity
meterMechanismCode
meterNumberOfDials
meterSerialNumber
mpaq
mprn
ndmq
pendingSupplierRegEffectiveDate
smartEquipmentTechnicalCode
}
}
Variables
{
"mprn": "yard-religious-this-opportunity-discuss"
}
Response
{
"data": {
"gasMeterpoint": {
"currentSupplierId": "52781465",
"currentSupplierRegEffectiveDate": "pretty-investment-order-present-avoid",
"dmq": "1.0",
"gasTransportId": "57881848",
"ldzId": "33303359",
"marketSectorCode": "provide-agent-would-education-president",
"meterCapacity": "positive-real-national-world-activity",
"meterMechanismCode": "writer-you-son-sing-owner",
"meterNumberOfDials": "part-think-air-manage-account",
"meterSerialNumber": "city-us-west-they-huge",
"mpaq": "1.0",
"mprn": "what-yeah-late-least-forward",
"ndmq": "1.0",
"pendingSupplierRegEffectiveDate": "chance-surface-service-almost-Mrs",
"smartEquipmentTechnicalCode": "west-air-science-soon-however"
}
}
}
gasMeterPointDetails
Type: GasMeterPointDetails
URL: https://api.octopus.energy/v1/graphql/
Search for the meter point details with given MPRN using Xoserve switching API.
Query Complexity: 6
Possible Errors:
- KT-GB-6630: We can't communicate with our address database right now to look up your address. Please try again.
- KT-GB-6635: The provided MPRN is not valid.
- KT-GB-6636: The provided MPRN is linked to an extinct meterpoint.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The MPRN of the meterpoint. |
Query
query GasMeterPointDetails($mprn: String!) {
gasMeterPointDetails(mprn: $mprn) {
relAddress {
...UniqueRELAddressTypeFragment
}
technicalDetails {
...GasMeterTechnicalDetailsFragment
}
}
}
Variables
{
"mprn": "trade-fund-entire-month-attack"
}
Response
{
"data": {
"gasMeterPointDetails": {
"relAddress": UniqueRELAddressType,
"technicalDetails": GasMeterTechnicalDetails
}
}
}
gasMeterReadings
Type: GasMeterReadingConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Fetch gas meter readings for a given account and meter
This field is a connection type. Connections are used to implement cursor based pagination.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Only fetch meter readings made since this date |
|
Only fetch meter readings made until this date |
Query
query GasMeterReadings(
$accountNumber: String!,
$after: String,
$before: String,
$eventTypes: [MeterReadingEventType],
$first: Int,
$last: Int,
$meterId: String!,
$readFrom: DateTime,
$readTo: DateTime
) {
gasMeterReadings(
accountNumber: $accountNumber,
after: $after,
before: $before,
eventTypes: $eventTypes,
first: $first,
last: $last,
meterId: $meterId,
readFrom: $readFrom,
readTo: $readTo
) {
edgeCount
edges {
...GasMeterReadingConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-3DD5DEB9",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"eventTypes": "CUSTOMER",
"first": 10,
"last": 10,
"meterId": "89184317",
"readFrom": "1994-10-21T06:19:37.590050+00:00",
"readTo": "2013-04-28T11:10:20.366718+00:00"
}
Response
{
"data": {
"gasMeterReadings": {
"edgeCount": 79,
"edges": [GasMeterReadingConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 38
}
}
}
gasPrepayLedgers
Type: PrepayLedgersType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-GB-6212: Meter does not exist.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query GasPrepayLedgers(
$accountNumber: String!,
$mprn: String!,
$serialNumber: String!
) {
gasPrepayLedgers(
accountNumber: $accountNumber,
mprn: $mprn,
serialNumber: $serialNumber
) {
creditLedger {
...SupplementaryLedgerTypeFragment
}
debtLedger {
...SupplementaryLedgerTypeFragment
}
paymentLedger {
...PrepayPaymentLedgerTypeFragment
}
}
}
Variables
{
"accountNumber": "A-373B4128",
"mprn": "kid-care-everybody-none-next",
"serialNumber": "activity-mission-describe-center-claim"
}
Response
{
"data": {
"gasPrepayLedgers": {
"creditLedger": SupplementaryLedgerType,
"debtLedger": SupplementaryLedgerType,
"paymentLedger": PrepayPaymentLedgerType
}
}
}
gbrCostOfUsage
Type: CostOfUsageResponse
URL: https://api.octopus.energy/v1/graphql/
Cost of usage for some period of charging.
Note: Currently only SMB products are supported for this query.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-1605: Invalid input.
- KT-GB-4301: No agreements found during the specified time period.
- KT-GB-4302: No costing definition was found for the product attached to the agreement.
- KT-GB-4303: The product during the specified period is not set up for sub-meter billing.
- KT-GB-4304: The costing definition for the product is not set up for cost of usage.
- KT-GB-4305: There was an exception during costing.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['10/m'] |
Arguments
| Name | Description |
|---|---|
|
Account number to calculate costs for. |
|
Provide costs for the first 'X' amount of consumption, measured in kWh. |
|
Flex device ID to filter costs for. |
|
Periods to calculate costs for. |
|
Filter results to a specific supply point. |
Query
query GbrCostOfUsage(
$accountNumber: String!,
$consumption: Decimal,
$deviceId: ID,
$periods: [DateTimeRangeInput]!,
$supplyPointId: ID
) {
gbrCostOfUsage(
accountNumber: $accountNumber,
consumption: $consumption,
deviceId: $deviceId,
periods: $periods,
supplyPointId: $supplyPointId
) {
periods {
...CostOfUsagePeriodFragment
}
}
}
Variables
{
"accountNumber": "A-85404070",
"consumption": "1.0",
"deviceId": "81563582",
"periods": DateTimeRangeInput,
"supplyPointId": "33660417"
}
Response
{
"data": {
"gbrCostOfUsage": {
"periods": [CostOfUsagePeriod]
}
}
}
getActiveCosLossProcessesForAccount
Type: [ActiveCosLossProcess]
URL: https://api.octopus.energy/v1/graphql/
Fetch all the active COS loss processes for the account.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can send loss objection for change of supplier
Arguments
| Name | Description |
|---|---|
|
The account number of the account of which to query active COS loss processes. |
Query
query GetActiveCosLossProcessesForAccount($accountNumber: String!) {
getActiveCosLossProcessesForAccount(accountNumber: $accountNumber) {
addressLine1
addressLine2
addressLine3
cosLossProcessFuelType
cosLossProcessId
hasOpenErroneousTransfer
postcode
supplyEndDate
}
}
Variables
{
"accountNumber": "A-99709CCF"
}
Response
{
"data": {
"getActiveCosLossProcessesForAccount": [
{
"addressLine1": "cup-relationship-manage-hit-art",
"addressLine2": "technology-ten-degree-maintain-capital",
"addressLine3": "price-where-investment-watch-different",
"cosLossProcessFuelType": "ELECTRICITY",
"cosLossProcessId": 17549397,
"hasOpenErroneousTransfer": true,
"postcode": "there-very-similar-when-food",
"supplyEndDate": "2019-01-21"
}
]
}
}
getEnergyIqData
Type: EnergyIqDataType
URL: https://api.octopus.energy/v1/graphql/
Get energy IQ data for a specific account. It can either be the current record for energy IQ score or a score estimation including ev/heatpump/solar.
Query Complexity: 6
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'getEnergyIqData' field is deprecated.
The energy IQ data feature is no longer supported.
- Marked as deprecated on 2026-06-05.
- Scheduled for removal on or after 2026-07-01.
Arguments
| Name | Description |
|---|---|
|
The number of the account to get energy IQ data for. |
|
Should the energy IQ estimation data include EV. |
|
Should the energy IQ estimation data include heatpump. |
|
Should the energy IQ estimation data include solar. |
|
Is the query for the current energy IQ record? If true no 'include' parameters may be provided. |
Query
query GetEnergyIqData(
$accountNumber: String!,
$includeEv: Boolean,
$includeHeatpump: Boolean,
$includeSolar: Boolean,
$isCurrentRecord: Boolean
) {
getEnergyIqData(
accountNumber: $accountNumber,
includeEv: $includeEv,
includeHeatpump: $includeHeatpump,
includeSolar: $includeSolar,
isCurrentRecord: $isCurrentRecord
) {
canAddHeatpump
canAddSolar
currentBill
elecCarRate
enqScore
hasEv
hasHeatpump
hasSolar
isCurrentRecord
newBill
}
}
Variables
{
"accountNumber": "A-9D41FE8C",
"includeEv": true,
"includeHeatpump": true,
"includeSolar": true,
"isCurrentRecord": true
}
Response
{
"data": {
"getEnergyIqData": {
"canAddHeatpump": true,
"canAddSolar": true,
"currentBill": 229.94,
"elecCarRate": 302.22,
"enqScore": 99,
"hasEv": true,
"hasHeatpump": true,
"hasSolar": true,
"isCurrentRecord": true,
"newBill": 153.1
}
}
}
getOnSiteJobsAppointmentByExternalReference
Type: OnSiteJobsAppointmentType
URL: https://api.octopus.energy/v1/graphql/
Get appointment by external reference and agent.
Query Complexity: 1
Possible Errors:
- KT-CT-13001: Appointment does not exist.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The agent for the appointment. |
|
The external reference of the appointment to return. |
Query
query GetOnSiteJobsAppointmentByExternalReference(
$agent: OnSiteJobsAgent!,
$externalReference: String!
) {
getOnSiteJobsAppointmentByExternalReference(
agent: $agent,
externalReference: $externalReference
) {
agent
appointmentActions {
...OnSiteJobsAppointmentActionConnectionTypeConnectionFragment
}
assets {
...OnSiteJobsAssetConnectionTypeConnectionFragment
}
cancellationCategory
cancellationSubCategory
cancelledAt
comments
commsStrategy
createdAt
deadlineDate
endAt
externalJobTypeMapping {
...OnSiteJobsExternalJobTypeMappingTypeFragment
}
externalReference
id
jobDetails
jobNotes
krakenWorkCategory
preferredStartDate
request {
...OnSiteJobsRequestTypeFragment
}
startAt
status
}
}
Variables
{
"agent": "GENERIC_AGENT",
"externalReference": "occur-customer-magazine-cup-management"
}
Response
{
"data": {
"getOnSiteJobsAppointmentByExternalReference": {
"agent": "GENERIC_AGENT",
"appointmentActions": OnSiteJobsAppointmentActionConnectionTypeConnection,
"assets": OnSiteJobsAssetConnectionTypeConnection,
"cancellationCategory": "CANCELLED_BY_CUSTOMER",
"cancellationSubCategory": "generation-customer-high-this-last",
"cancelledAt": "1983-01-25T15:34:50.171044+00:00",
"comments": "section-young-level-middle-road",
"commsStrategy": "SEND_ALL",
"createdAt": "1977-02-13T16:15:07.605420+00:00",
"deadlineDate": "1994-11-16",
"endAt": "2000-10-11T12:20:55.248658+00:00",
"externalJobTypeMapping": OnSiteJobsExternalJobTypeMappingType,
"externalReference": "him-able-every-I-majority",
"id": "caa4bb68-f794-415f-92d4-49fe3fd74e29",
"jobDetails": {"key": "value"},
"jobNotes": {"key": "value"},
"krakenWorkCategory": "ACCURACY_TEST",
"preferredStartDate": "1978-04-06",
"request": OnSiteJobsRequestType,
"startAt": "2006-04-07T01:52:11.965615+00:00",
"status": "REQUIRES_TIMESLOT"
}
}
}
getOnSiteJobsAppointmentById
Type: OnSiteJobsAppointmentType
URL: https://api.octopus.energy/v1/graphql/
Get a specific appointment by Kraken ID.
Query Complexity: 1
Possible Errors:
- KT-CT-13001: Appointment does not exist.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The Kraken ID of the appointment to return. |
Query
query GetOnSiteJobsAppointmentById($appointmentId: UUID) {
getOnSiteJobsAppointmentById(appointmentId: $appointmentId) {
agent
appointmentActions {
...OnSiteJobsAppointmentActionConnectionTypeConnectionFragment
}
assets {
...OnSiteJobsAssetConnectionTypeConnectionFragment
}
cancellationCategory
cancellationSubCategory
cancelledAt
comments
commsStrategy
createdAt
deadlineDate
endAt
externalJobTypeMapping {
...OnSiteJobsExternalJobTypeMappingTypeFragment
}
externalReference
id
jobDetails
jobNotes
krakenWorkCategory
preferredStartDate
request {
...OnSiteJobsRequestTypeFragment
}
startAt
status
}
}
Variables
{
"appointmentId": "1b5ecb6d-4ebf-4270-ac25-0111a697093d"
}
Response
{
"data": {
"getOnSiteJobsAppointmentById": {
"agent": "GENERIC_AGENT",
"appointmentActions": OnSiteJobsAppointmentActionConnectionTypeConnection,
"assets": OnSiteJobsAssetConnectionTypeConnection,
"cancellationCategory": "CANCELLED_BY_CUSTOMER",
"cancellationSubCategory": "four-cold-myself-fear-ground",
"cancelledAt": "2005-04-27T19:34:17.030059+00:00",
"comments": "offer-prevent-health-business-exist",
"commsStrategy": "SEND_ALL",
"createdAt": "2019-12-13T14:59:26.231198+00:00",
"deadlineDate": "2017-06-11",
"endAt": "2003-01-05T21:12:27.723610+00:00",
"externalJobTypeMapping": OnSiteJobsExternalJobTypeMappingType,
"externalReference": "generation-during-those-understand-major",
"id": "de7acb73-007d-4b19-b45f-a2acee6a708f",
"jobDetails": {"key": "value"},
"jobNotes": {"key": "value"},
"krakenWorkCategory": "ACCURACY_TEST",
"preferredStartDate": "2023-05-07",
"request": OnSiteJobsRequestType,
"startAt": "2017-06-14T05:45:34.747609+00:00",
"status": "REQUIRES_TIMESLOT"
}
}
}
getOnSiteJobsAppointmentSlots
Type: OnSiteJobsAppointmentSlotResultsType
URL: https://api.octopus.energy/v1/graphql/
Get appointment slot results using appointment booking session ID.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Appointment booking session ID to fetch slots for. ID can be obtained via |
|
Appointment date (inclusive) to fetch slots from. |
Query
query GetOnSiteJobsAppointmentSlots(
$appointmentBookingSessionId: UUID!,
$appointmentDate: Date!
) {
getOnSiteJobsAppointmentSlots(
appointmentBookingSessionId: $appointmentBookingSessionId,
appointmentDate: $appointmentDate
) {
isComplete
slots {
...OnSiteJobsAppointmentSlotTypeFragment
}
}
}
Variables
{
"appointmentBookingSessionId": "d00f8ad0-0180-4b4f-ae2d-be39d194c0ae",
"appointmentDate": "1991-03-15"
}
Response
{
"data": {
"getOnSiteJobsAppointmentSlots": {
"isComplete": true,
"slots": [OnSiteJobsAppointmentSlotType]
}
}
}
getOnSiteJobsCheckResults
Type: OnSiteJobsCheckResultsType
URL: https://api.octopus.energy/v1/graphql/
Get check results for creating requests and appointments.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Job type for appointment checks. |
|
Supply point identifier to market name mapping. If this is provided, |
|
List of internal IDs of supply points. If this is provided, |
Query
query GetOnSiteJobsCheckResults(
$jobType: String,
$supplyPointIdentifierToMarketNameMapping: [SupplyPointIdentifierToMarketNameMappingInput],
$supplyPointInternalIds: [Int]
) {
getOnSiteJobsCheckResults(
jobType: $jobType,
supplyPointIdentifierToMarketNameMapping: $supplyPointIdentifierToMarketNameMapping,
supplyPointInternalIds: $supplyPointInternalIds
) {
appointmentCheckResults {
...CheckResultTypeFragment
}
canCreateAppointment
canCreateRequest
hasAppointmentWarnings
hasRequestWarnings
requestCheckResults {
...CheckResultTypeFragment
}
}
}
Variables
{
"jobType": "whatever-past-likely-yes-according",
"supplyPointIdentifierToMarketNameMapping": SupplyPointIdentifierToMarketNameMappingInput,
"supplyPointInternalIds": 8
}
Response
{
"data": {
"getOnSiteJobsCheckResults": {
"appointmentCheckResults": [CheckResultType],
"canCreateAppointment": true,
"canCreateRequest": true,
"hasAppointmentWarnings": true,
"hasRequestWarnings": true,
"requestCheckResults": [CheckResultType]
}
}
}
getOnSiteJobsJobTypes
Type: [OnSiteJobsJobTypeType]
URL: https://api.octopus.energy/v1/graphql/
Get available job types for an on-site jobs request.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ID of the request for which to fetch available job types. |
|
Work category to filter job types by. If it's left as blank, all job types will be returned. |
Query
query GetOnSiteJobsJobTypes(
$requestId: UUID!,
$workCategory: OnSiteJobsWorkCategory
) {
getOnSiteJobsJobTypes(
requestId: $requestId,
workCategory: $workCategory
) {
id
name
}
}
Variables
{
"requestId": "b26e94c6-64f6-46aa-b16f-7ac20c36f2b0",
"workCategory": "ACCURACY_TEST"
}
Response
{
"data": {
"getOnSiteJobsJobTypes": [
{
"id": "88218075",
"name": "apply-stand-center-federal-drive"
}
]
}
}
getOnSiteJobsRequestById
Type: OnSiteJobsRequestType
URL: https://api.octopus.energy/v1/graphql/
Get a specific request by ID.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ID of the request to return. |
Query
query GetOnSiteJobsRequestById($requestId: UUID) {
getOnSiteJobsRequestById(requestId: $requestId) {
account
agent
appointments {
...OnSiteJobsAppointmentConnectionTypeConnectionFragment
}
assets {
...OnSiteJobsAssetConnectionTypeConnectionFragment
}
comment
createdBy
externalReference
id
isEmergency
marketSupplyPoints {
...SupplyPointConnectionTypeConnectionFragment
}
overallActionsStatus
property {
...PropertyTypeFragment
}
reason
requestActions {
...OnSiteJobsRequestActionConnectionTypeConnectionFragment
}
status
subReason
}
}
Variables
{
"requestId": "b014107c-2d86-41bf-ab31-9ab402b9625b"
}
Response
{
"data": {
"getOnSiteJobsRequestById": {
"account": "reflect-relate-law-instead-management",
"agent": "mission-culture-field-final-explain",
"appointments": OnSiteJobsAppointmentConnectionTypeConnection,
"assets": OnSiteJobsAssetConnectionTypeConnection,
"comment": "artist-might-between-use-south",
"createdBy": 40,
"externalReference": "most-house-executive-attention-nearly",
"id": "86a35d25-985e-4de4-a443-3e14862e2e58",
"isEmergency": true,
"marketSupplyPoints": SupplyPointConnectionTypeConnection,
"overallActionsStatus": "PENDING",
"property": PropertyType,
"reason": "gun-painting-single-may-strategy",
"requestActions": OnSiteJobsRequestActionConnectionTypeConnection,
"status": "PENDING",
"subReason": "bad-appear-remember-effort-space"
}
}
}
getOnSiteJobsRequests
Type: OnSiteJobsRequestConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Filter On-Site Jobs Requests.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
A list of account numbers to filter requests by. |
|
|
|
|
|
|
|
|
|
A list of statuses to filter requests by. |
|
List of internal IDs of supply points to filter requests by. If this is provided, |
|
A list of supply point identifiers to filter requests by. If this is provided, |
Query
query GetOnSiteJobsRequests(
$accountNumbers: [NonEmptyString!],
$after: String,
$before: String,
$first: Int,
$last: Int,
$statuses: [OnSiteJobsRequestStatus],
$supplyPointInternalIds: [Int],
$supplyPointsToMarketNamesMapping: [SupplyPointIdentifierToMarketNameMappingInput]
) {
getOnSiteJobsRequests(
accountNumbers: $accountNumbers,
after: $after,
before: $before,
first: $first,
last: $last,
statuses: $statuses,
supplyPointInternalIds: $supplyPointInternalIds,
supplyPointsToMarketNamesMapping: $supplyPointsToMarketNamesMapping
) {
edgeCount
edges {
...OnSiteJobsRequestConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumbers": "rest-decision-control-this-media",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"statuses": "PENDING",
"supplyPointInternalIds": 38,
"supplyPointsToMarketNamesMapping": SupplyPointIdentifierToMarketNameMappingInput
}
Response
{
"data": {
"getOnSiteJobsRequests": {
"edgeCount": 43,
"edges": [OnSiteJobsRequestConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 28
}
}
}
getProjectedRegionalCarbonIntensity
Type: ProjectedRegionalCarbonIntensityType
URL: https://api.octopus.energy/v1/graphql/
Get regional carbon intensity forecast.
Query Complexity: 6
Possible Errors:
- KT-GB-1301: The provided postcode is not a UK postcode.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The postcode for which to fetch regional carbon intensity forecast. |
Query
query GetProjectedRegionalCarbonIntensity($postcode: String!) {
getProjectedRegionalCarbonIntensity(postcode: $postcode) {
projectedRegionalCarbonIntensity {
...ProjectedRegionalCarbonIntensitiesTypeFragment
}
}
}
Variables
{
"postcode": "wonder-trouble-music-film-fill"
}
Response
{
"data": {
"getProjectedRegionalCarbonIntensity": {
"projectedRegionalCarbonIntensity": [ProjectedRegionalCarbonIntensitiesType]
}
}
}
getSolarGenerationEstimate
Type: SolarGenerationEstimatesType
URL: https://api.octopus.energy/v1/graphql/
Get an estimate of the number of kWh an average domestic solar installation would produce for a given postcode.
Query Complexity: 1
Possible Errors:
- KT-GB-1301: The provided postcode is not a UK postcode.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The start date from which to pull a weeks worth of data. |
|
The postcode area to fetch estimate for. |
Query
query GetSolarGenerationEstimate(
$fromDate: Date!,
$postcode: String!
) {
getSolarGenerationEstimate(
fromDate: $fromDate,
postcode: $postcode
) {
solarGenerationEstimates {
...SolarGenerationEstimateTypeFragment
}
}
}
Variables
{
"fromDate": "1971-01-23",
"postcode": "can-right-something-magazine-speech"
}
Response
{
"data": {
"getSolarGenerationEstimate": {
"solarGenerationEstimates": [SolarGenerationEstimateType]
}
}
}
getSpringElectricityComparison
Type: SpringElectricityComparisonType
URL: https://api.octopus.energy/v1/graphql/
Get spring clock change electricity consumption comparison data for a specific account and property.
Query Complexity: 6
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'getSpringElectricityComparison' field is deprecated.
This feature is no longer supported.
- Marked as deprecated on 2026-06-05.
- Scheduled for removal on or after 2026-07-01.
Arguments
| Name | Description |
|---|---|
|
The account number to get comparison data for. |
|
The ID for the specific property to get comparison data for. |
Query
query GetSpringElectricityComparison(
$accountNumber: String!,
$propertyId: Int!
) {
getSpringElectricityComparison(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
absoluteReductionPercentage
isReduction
postPeakPercentage
priorPeakPercentage
relativeReductionPercentage
}
}
Variables
{
"accountNumber": "A-5915D620",
"propertyId": 22571512
}
Response
{
"data": {
"getSpringElectricityComparison": {
"absoluteReductionPercentage": 466.67,
"isReduction": true,
"postPeakPercentage": 792.47,
"priorPeakPercentage": 959.53,
"relativeReductionPercentage": 14.86
}
}
}
getWinterGasComparison
Type: WinterGasComparisonResultType
URL: https://api.octopus.energy/v1/graphql/
Get gas consumption comparison data for a specific account and property.
Query Complexity: 6
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number to get comparison data for. |
|
The ID for the specific property to get comparison data for. |
Query
query GetWinterGasComparison(
$accountNumber: String!,
$propertyId: Int!
) {
getWinterGasComparison(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
winterGasComparison {
...WinterGasComparisonTypeFragment
}
}
}
Variables
{
"accountNumber": "A-20A6EA77",
"propertyId": 69919319
}
Response
{
"data": {
"getWinterGasComparison": {
"winterGasComparison": [WinterGasComparisonType]
}
}
}
goodsProducts
Type: GoodsProductConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
List Goods products given a market.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Code of the products to filter by. |
|
|
|
|
|
Market name of the products to list. |
|
Types of the products to filter by. |
Query
query GoodsProducts(
$after: String,
$before: String,
$code: [String],
$first: Int,
$last: Int,
$marketName: String!,
$productType: [String]
) {
goodsProducts(
after: $after,
before: $before,
code: $code,
first: $first,
last: $last,
marketName: $marketName,
productType: $productType
) {
edgeCount
edges {
...GoodsProductConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"code": "door-agency-study-college-consumer",
"first": 10,
"last": 10,
"marketName": "determine-budget-one-head-card",
"productType": "scene-himself-result-political-pick"
}
Response
{
"data": {
"goodsProducts": {
"edgeCount": 61,
"edges": [GoodsProductConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 81
}
}
}
goodsPurchases
Type: [GoodsPurchase]
URL: https://api.octopus.energy/v1/graphql/
List purchases for an account.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number. |
Query
query GoodsPurchases($accountNumber: String!) {
goodsPurchases(accountNumber: $accountNumber) {
clientParams
code
goodsGrants {
...GoodsGrantFragment
}
goodsSaleItems {
...GoodsSaleItemFragment
}
ledgerNumber
marketName
marketParams
}
}
Variables
{
"accountNumber": "A-D377C57F"
}
Response
{
"data": {
"goodsPurchases": [
{
"clientParams": {"key": "value"},
"code": "I-every-himself-former-wait",
"goodsGrants": [GoodsGrant],
"goodsSaleItems": [GoodsSaleItem],
"ledgerNumber": "movie-structure-business-focus-rate",
"marketName": "nation-fine-ago-partner-card",
"marketParams": {"key": "value"}
}
]
}
}
goodsQuotes
Type: [GoodsQuote]
URL: https://api.octopus.energy/v1/graphql/
List quotes given an account number or retrieve a Goods quote given a quote code.
Query Complexity: 1
Possible Errors:
- KT-CT-8201: Received an invalid quoteId.
- KT-CT-8204: Invalid arguments.
- KT-CT-8223: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
The quote code. |
Query
query GoodsQuotes(
$accountNumber: String,
$quoteCode: String
) {
goodsQuotes(
accountNumber: $accountNumber,
quoteCode: $quoteCode
) {
code
goodsQuotedProducts {
...GoodsQuotedProductFragment
}
hasQuoteExpired
id
quotedAt
totalNetAmount
}
}
Variables
{
"accountNumber": "A-68B85E81",
"quoteCode": "task-produce-how-question-keep"
}
Response
{
"data": {
"goodsQuotes": [
{
"code": "space-industry-way-cold-almost",
"goodsQuotedProducts": [GoodsQuotedProduct],
"hasQuoteExpired": true,
"id": "93669234",
"quotedAt": "2023-09-07T02:29:09.037878+00:00",
"totalNetAmount": 33
}
]
}
}
heatPumpControllerConfiguration
Type: ControllerAndZoneConfiguration
URL: https://api.octopus.energy/v1/graphql/
Heat pump controller, zones and sensor configuration.
Query Complexity: 2
Possible Errors:
- KT-CT-4305: Unable to fetch heating controller configuration.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'heatPumpControllerConfiguration' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Query
query HeatPumpControllerConfiguration(
$accountNumber: String!,
$euid: ID!
) {
heatPumpControllerConfiguration(
accountNumber: $accountNumber,
euid: $euid
) {
controller {
...ControllerConfigurationFragment
}
heatPump {
...HeatPumpConfigurationFragment
}
zones {
...ZoneInformationFragment
}
}
}
Variables
{
"accountNumber": "A-43A238D7",
"euid": "52136689"
}
Response
{
"data": {
"heatPumpControllerConfiguration": {
"controller": ControllerConfiguration,
"heatPump": HeatPumpConfiguration,
"zones": [ZoneInformation]
}
}
}
heatPumpControllerStatus
Type: ControllerStatus
URL: https://api.octopus.energy/v1/graphql/
Retrieve the heat pump controller device status.
Query Complexity: 2
Possible Errors:
- KT-CT-4303: Unable to fetch device status.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'heatPumpControllerStatus' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Query
query HeatPumpControllerStatus(
$accountNumber: String!,
$euid: ID!
) {
heatPumpControllerStatus(
accountNumber: $accountNumber,
euid: $euid
) {
sensors {
...SensorStatusFragment
}
zones {
...ZoneStatusFragment
}
}
}
Variables
{
"accountNumber": "A-04B04FCB",
"euid": "77349438"
}
Response
{
"data": {
"heatPumpControllerStatus": {
"sensors": [SensorStatus],
"zones": [ZoneStatus]
}
}
}
heatPumpDevice
Type: HeatPumpDeviceType
URL: https://api.octopus.energy/v1/graphql/
The currently active heat pump device.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query HeatPumpDevice(
$accountNumber: String!,
$propertyId: Int!
) {
heatPumpDevice(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
krakenflexDeviceId
provider
}
}
Variables
{
"accountNumber": "A-4D04629A",
"propertyId": 83169768
}
Response
{
"data": {
"heatPumpDevice": {
"krakenflexDeviceId": "32804814",
"provider": "BYD"
}
}
}
heatPumpStatus
Type: HeatPumpStatusType
URL: https://api.octopus.energy/v1/graphql/
A heat pump registered with KrakenFlex for a given account
Query Complexity: 2
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4360: Device status could not be fetched.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Arguments
| Name | Description |
|---|---|
|
Query
query HeatPumpStatus($accountNumber: String!) {
heatPumpStatus(accountNumber: $accountNumber) {
climateControlStatus {
...ClimateControlDetailsTypeFragment
}
isConnected
waterTemperatureStatus {
...WaterTemperatureDetailsTypeFragment
}
}
}
Variables
{
"accountNumber": "A-BBAA8BC7"
}
Response
{
"data": {
"heatPumpStatus": {
"climateControlStatus": ClimateControlDetailsType,
"isConnected": true,
"waterTemperatureStatus": WaterTemperatureDetailsType
}
}
}
heatPumpVariants
Type: [HeatPumpVariantsType]
URL: https://api.octopus.energy/v1/graphql/
All heat pumps and their details.
Query Complexity: 1
Possible Errors:
- KT-CT-4361: No heat pumps of that make found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Deprecated
The 'heatPumpVariants' field is deprecated.
Please use 'flexSupportedDevices' instead.
- Marked as deprecated on 2026-04-15.
- Scheduled for removal on or after 2026-10-15.
Arguments
| Name | Description |
|---|---|
|
Only return (non-) deprecated heat pumps. |
|
Only return heat pumps of a specific make. |
Query
query HeatPumpVariants(
$isDeprecated: Boolean,
$make: String
) {
heatPumpVariants(
isDeprecated: $isDeprecated,
make: $make
) {
make
models {
...HeatPumpVariantModelsTypeFragment
}
}
}
Variables
{
"isDeprecated": true,
"make": "feel-hair-foot-I-upon"
}
Response
{
"data": {
"heatPumpVariants": [
{
"make": "garden-bank-race-official-day",
"models": [HeatPumpVariantModelsType]
}
]
}
}
inboundCallAverageWaitTime
Type: InboundCallAverageWaitTimeType
URL: https://api.octopus.energy/v1/graphql/
Get the average wait time for an inbound call.
Query Complexity: 2
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Query
query InboundCallAverageWaitTime {
inboundCallAverageWaitTime {
recent
yesterday
}
}
Response
{
"data": {
"inboundCallAverageWaitTime": {
"recent": 19,
"yesterday": 73
}
}
}
inboundCallAverageWaitTimeForAttributes
Type: InboundCallAverageWaitTimeForAttributesType
URL: https://api.octopus.energy/v1/graphql/
Get the average wait time for inbound calls with the given routing attributes. Note that calls with more attributes than those given will be included.
Query Complexity: 2
Possible Errors:
- KT-CT-11821: No calls found matching the given routing attributes.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
Routing attribute references to filter calls by. Calls must have all of the given attributes to be included. |
Query
query InboundCallAverageWaitTimeForAttributes($attributes: [String]!) {
inboundCallAverageWaitTimeForAttributes(attributes: $attributes) {
recent
yesterday
}
}
Variables
{
"attributes": "heavy-lose-require-most-surface"
}
Response
{
"data": {
"inboundCallAverageWaitTimeForAttributes": {
"recent": 21,
"yesterday": 14
}
}
}
inkCommsTemplate
Type: String!
URL: https://api.octopus.energy/v1/graphql/
Fetch the content of a given comms template name.
Query Complexity: 1
Possible Errors:
- KT-CT-7648: The comms template was not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query ink messages
Arguments
| Name | Description |
|---|---|
|
The identifier of the comms template. |
Query
query InkCommsTemplate($templateIdentifier: String!) {
inkCommsTemplate(templateIdentifier: $templateIdentifier)
}
Variables
{
"templateIdentifier": "21910380"
}
Response
{
"data": {
"inkCommsTemplate": "accept-role-city-its-few"
}
}
inkConversation
Type: InkConversation!
URL: https://api.octopus.energy/v1/graphql/
Get the Ink conversation for a given account.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
- KT-CT-7610: No Ink conversation for account.
- KT-CT-7612: The Ink conversation was not found.
- KT-CT-7617: Must supply account number or relay id to get a conversation.
- KT-CT-7638: Invalid conversation ID.
- KT-CT-7658: Unauthorized to access this conversation.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query ink conversations
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
The conversation's relay id. |
Query
query InkConversation(
$accountNumber: String,
$conversationRelayId: String
) {
inkConversation(
accountNumber: $accountNumber,
conversationRelayId: $conversationRelayId
) {
accountNumber
accountUsers {
...AccountUserTypeFragment
}
buckets {
...InkBucketFragment
}
contactChannelIdentities {
...InkContactChannelIdentitiesFragment
}
events {
...InkConversationEventsConnectionFragment
}
id
lastMessageAt
status
tags {
...InkTagFragment
}
}
}
Variables
{
"accountNumber": "A-62C251EB",
"conversationRelayId": "95479252"
}
Response
{
"data": {
"inkConversation": {
"accountNumber": "A-16EA23E7",
"accountUsers": [AccountUserType],
"buckets": [InkBucket],
"contactChannelIdentities": InkContactChannelIdentities,
"events": InkConversationEventsConnection,
"id": "70940695",
"lastMessageAt": "2011-02-04T15:41:04.769640+00:00",
"status": "OPEN",
"tags": [InkTag]
}
}
}
inkLiveChatConversations
Type: InkConversationsConnection!
URL: https://api.octopus.energy/v1/graphql/
Returns a list of paginated conversations associated with the user.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query ink conversations
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
Filter by conversation's status. |
Query
query InkLiveChatConversations(
$after: String,
$before: String,
$first: Int,
$last: Int,
$status: String
) {
inkLiveChatConversations(
after: $after,
before: $before,
first: $first,
last: $last,
status: $status
) {
edges {
...InkConversationsEdgeFragment
}
pageInfo {
...PageInfoFragment
}
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"status": "debate-each-commercial-citizen-hope"
}
Response
{
"data": {
"inkLiveChatConversations": {
"edges": [InkConversationsEdge],
"pageInfo": PageInfo
}
}
}
inkMessage
Type: InkMessage!
URL: https://api.octopus.energy/v1/graphql/
Get the content for a given message.
Query Complexity: 1
Possible Errors:
- KT-CT-7611: The message was not found.
- KT-CT-7638: Invalid conversation ID.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query ink messages
Arguments
| Name | Description |
|---|---|
|
The message's relay id. |
Query
query InkMessage($messageRelayId: String!) {
inkMessage(messageRelayId: $messageRelayId) {
... on InkEmail {
...InkEmailFragment
}
... on InkGenericMessage {
...InkGenericMessageFragment
}
... on InkLine {
...InkLineFragment
}
... on InkLiveChatMessage {
...InkLiveChatMessageFragment
}
... on InkPost {
...InkPostFragment
}
... on InkSMS {
...InkSMSFragment
}
... on InkTwilioWhatsApp {
...InkTwilioWhatsAppFragment
}
... on InkWhatsApp {
...InkWhatsAppFragment
}
}
}
Variables
{
"messageRelayId": "99960429"
}
Response
{
"data": {
"inkMessage": InkEmail
}
}
inkMessageAttributes
Type: InkMessageAttributes!
URL: https://api.octopus.energy/v1/graphql/
Get attributes of a message at time of query.
Query Complexity: 1
Possible Errors:
- KT-CT-7611: The message was not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query ink messages
Arguments
| Name | Description |
|---|---|
|
The message's vendor. |
|
The message's vendor id. |
Query
query InkMessageAttributes(
$vendor: String!,
$vendorId: String!
) {
inkMessageAttributes(
vendor: $vendor,
vendorId: $vendorId
) {
accounts
accountType
buckets
conversationId
hourOccurredAt
hoursWaiting
isAssignedToUserBucket
isFirstFromContact
isNewThread
opsTeam
recentlyReceivedAutoReplies
replyToCommsSms
weekDayOccurredAt
}
}
Variables
{
"vendor": "hold-late-easy-girl-picture",
"vendorId": "79668849"
}
Response
{
"data": {
"inkMessageAttributes": {
"accounts": "back-before-go-sea-ability",
"accountType": "front-exactly-each-seat-good",
"buckets": "now-consumer-part-effort-former",
"conversationId": 41242228,
"hourOccurredAt": 13,
"hoursWaiting": 18,
"isAssignedToUserBucket": true,
"isFirstFromContact": true,
"isNewThread": true,
"opsTeam": "amount-around-stuff-think-look",
"recentlyReceivedAutoReplies": "physical-different-among-until-goal",
"replyToCommsSms": "less-difficult-station-as-yeah",
"weekDayOccurredAt": 65
}
}
}
inkMessageTextContent
Type: String!
URL: https://api.octopus.energy/v1/graphql/
Fetch the text content of a given message.
Query Complexity: 1
Possible Errors:
- KT-CT-7611: The message was not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query ink message text content
Arguments
| Name | Description |
|---|---|
|
The message's id or relay id. |
Query
query InkMessageTextContent($messageId: ID!) {
inkMessageTextContent(messageId: $messageId)
}
Variables
{
"messageId": "24099305"
}
Response
{
"data": {
"inkMessageTextContent": "business-thing-executive-produce-hair"
}
}
internalCompanies
Type: InternalCompanyConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get all internal companies.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query internal companies
Query
query InternalCompanies(
$after: String,
$before: String,
$first: Int,
$last: Int
) {
internalCompanies(
after: $after,
before: $before,
first: $first,
last: $last
) {
edgeCount
edges {
...InternalCompanyConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10
}
Response
{
"data": {
"internalCompanies": {
"edgeCount": 71,
"edges": [InternalCompanyConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 22
}
}
}
internalCompany
Type: InternalCompanyType
URL: https://api.octopus.energy/v1/graphql/
Get an internal company by a set of criteria. Criteria will be added as needed, check documentation for the criteria object to see what is currently supported.
Query Complexity: 1
Possible Errors:
- KT-CT-14401: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query internal companies
Arguments
| Name | Description |
|---|---|
|
Criteria to identify the internal company. |
Query
query InternalCompany($criteria: SearchCriteriaInput!) {
internalCompany(criteria: $criteria) {
displayableNumber
id
legalAddress {
...RichAddressTypeFragment
}
name
primaryRegistrationNumber
primaryTaxIdentifierNumber
secondaryRegistrationNumber
}
}
Variables
{
"criteria": SearchCriteriaInput
}
Response
{
"data": {
"internalCompany": {
"displayableNumber": "foot-including-until-front-growth",
"id": "47072318",
"legalAddress": RichAddressType,
"name": "tell-meeting-would-tonight-summer",
"primaryRegistrationNumber": "democratic-operation-evening-success-rather",
"primaryTaxIdentifierNumber": "range-short-gas-fish-likely",
"secondaryRegistrationNumber": "other-control-field-top-sign"
}
}
}
isCustomerEligibleToGiveFeedbackFollowingCall
Type: Boolean
URL: https://api.octopus.energy/v1/graphql/
Check if customer is eligible to give feedback following a phone call.
Query Complexity: 1
Possible Errors:
- KT-CT-5519: Voice call not found.
- KT-CT-5521: Eligibility configuration not found.
- KT-CT-5522: Invalid eligibility configuration.
- KT-CT-5523: Invalid account or account user.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can check customer feedback eligibility
Arguments
| Name | Description |
|---|---|
|
Number of the account. |
|
Number of the account user. |
|
ID of the voice call. |
Query
query IsCustomerEligibleToGiveFeedbackFollowingCall(
$accountNumber: String!,
$accountUserNumber: String!,
$callId: Int!
) {
isCustomerEligibleToGiveFeedbackFollowingCall(
accountNumber: $accountNumber,
accountUserNumber: $accountUserNumber,
callId: $callId
)
}
Variables
{
"accountNumber": "A-7A788D57",
"accountUserNumber": "U-B06CB77C",
"callId": 81360821
}
Response
{
"data": {
"isCustomerEligibleToGiveFeedbackFollowingCall": true
}
}
isCustomerEligibleToGiveFeedbackFollowingEmail
Type: Boolean
URL: https://api.octopus.energy/v1/graphql/
Check if customer is eligible to give feedback following an email conversation.
Query Complexity: 1
Possible Errors:
- KT-CT-5520: Ink conversation not found.
- KT-CT-5521: Eligibility configuration not found.
- KT-CT-5522: Invalid eligibility configuration.
- KT-CT-5523: Invalid account or account user.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can check customer feedback eligibility
Arguments
| Name | Description |
|---|---|
|
Number of the account. |
|
Number of the account user. |
|
Datetime when the conversation was closed. |
|
ID of the Ink conversation. |
Query
query IsCustomerEligibleToGiveFeedbackFollowingEmail(
$accountNumber: String!,
$accountUserNumber: String!,
$conversationClosedAt: DateTime!,
$inkConversationId: Int!
) {
isCustomerEligibleToGiveFeedbackFollowingEmail(
accountNumber: $accountNumber,
accountUserNumber: $accountUserNumber,
conversationClosedAt: $conversationClosedAt,
inkConversationId: $inkConversationId
)
}
Variables
{
"accountNumber": "A-C6AAAF99",
"accountUserNumber": "U-049C7A98",
"conversationClosedAt": "2011-07-11T09:29:57.516138+00:00",
"inkConversationId": 52121719
}
Response
{
"data": {
"isCustomerEligibleToGiveFeedbackFollowingEmail": true
}
}
isEnrolledInCustomerFlexibilityCampaign
Type: Boolean
URL: https://api.octopus.energy/v1/graphql/
Check if an account is enrolled in a Customer Flexibility Campaign.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-12201: Campaign not found.
- KT-CT-12202: Supply point not found.
- KT-CT-12203: Market supply point not supported.
- KT-CT-12204: Market supply point is not associated with the account.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number to check enrollment for. |
|
The slug of the campaign to check enrollment for. |
|
The supply point identifier to check enrollment for. |
Query
query IsEnrolledInCustomerFlexibilityCampaign(
$accountNumber: String!,
$campaignSlug: String!,
$supplyPointIdentifier: String!
) {
isEnrolledInCustomerFlexibilityCampaign(
accountNumber: $accountNumber,
campaignSlug: $campaignSlug,
supplyPointIdentifier: $supplyPointIdentifier
)
}
Variables
{
"accountNumber": "A-D029C4B0",
"campaignSlug": "specific-consider-main-husband-none",
"supplyPointIdentifier": "75986453"
}
Response
{
"data": {
"isEnrolledInCustomerFlexibilityCampaign": true
}
}
isPasswordResetTokenValid
Type: Boolean
URL: https://api.octopus.energy/v1/graphql/
Check validity of a password reset token.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Arguments
| Name | Description |
|---|---|
|
Password reset token to check. |
|
Base64 encoded user id. |
Query
query IsPasswordResetTokenValid(
$token: String!,
$userId: String!
) {
isPasswordResetTokenValid(
token: $token,
userId: $userId
)
}
Variables
{
"token": "contain-game-glass-onto-production",
"userId": "28744052"
}
Response
{
"data": {
"isPasswordResetTokenValid": true
}
}
joinSupplierProcess
Type: JoinSupplierProcessType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-10332: Join supplier process not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query lifecycle processes
Arguments
| Name | Description |
|---|---|
|
The join supplier process number, e.g. JS-12345678. |
Query
query JoinSupplierProcess($number: String!) {
joinSupplierProcess(number: $number) {
contractIdentifiers
currentProcessData {
...JoinSupplierProcessDataTypeFragment
}
id
ledgerAssignments {
...JoinSupplierLedgerAssignmentConnectionTypeConnectionFragment
}
number
stage
status
subtype
supplyPoints {
...SupplyPointConnectionTypeConnectionFragment
}
}
}
Variables
{
"number": "consider-out-off-ago-likely"
}
Response
{
"data": {
"joinSupplierProcess": {
"contractIdentifiers": "moment-bit-talk-win-need",
"currentProcessData": JoinSupplierProcessDataType,
"id": "36652878",
"ledgerAssignments": JoinSupplierLedgerAssignmentConnectionTypeConnection,
"number": "own-require-surface-clearly-that",
"stage": "stage-it-those-rise-fear",
"status": "PENDING",
"subtype": "newspaper-few-too-father-trip",
"supplyPoints": SupplyPointConnectionTypeConnection
}
}
}
krakenVersion
Type: KrakenVersionType
URL: https://api.octopus.energy/v1/graphql/
The current version of kraken.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['100/m'] |
Query
query KrakenVersion {
krakenVersion {
isPinned
number
SHA
}
}
Response
{
"data": {
"krakenVersion": {
"isPinned": true,
"number": "a-region-fear-mouth-society",
"SHA": "dog-service-open-identify-also"
}
}
}
leadBlocklistValidations
Type: LeadBlockListValidationOutput
URL: https://api.octopus.energy/v1/graphql/
Run a blocklist validation out of some dynamic client entry types.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
List of client-configured black list entry types. |
Query
query LeadBlocklistValidations($blockListEntries: LeadBlockListValidationInput) {
leadBlocklistValidations(blockListEntries: $blockListEntries) {
blockListHits
valid
}
}
Variables
{
"blockListEntries": LeadBlockListValidationInput
}
Response
{
"data": {
"leadBlocklistValidations": {
"blockListHits": "place-recent-magazine-nearly-also",
"valid": true
}
}
}
leadByNumber
Type: LeadOutput
URL: https://api.octopus.energy/v1/graphql/
Get lead details by number.
Query Complexity: 1
Possible Errors:
- KT-CT-8907: Lead not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
Lead number. |
Query
query LeadByNumber($number: String) {
leadByNumber(number: $number) {
accountNumber
billingAddress {
...AddressOutputFragment
}
billingName
billingRichAddress {
...RichAddressTypeFragment
}
brand
consents {
...ConsentOutputFragment
}
email
extraDetailItems {
...ExtraDetailFragment
}
familyName
funnel {
...SalesFunnelFragment
}
givenName
leadId
leadType
nationalId
number
phoneNumber
stage
}
}
Variables
{
"number": "inside-prevent-support-place-international"
}
Response
{
"data": {
"leadByNumber": {
"accountNumber": "A-54659B89",
"billingAddress": AddressOutput,
"billingName": "most-military-study-capital-region",
"billingRichAddress": RichAddressType,
"brand": "song-research-stay-me-college",
"consents": [ConsentOutput],
"email": "right-and-place-grow-Democrat",
"extraDetailItems": [ExtraDetail],
"familyName": "Livingston",
"funnel": SalesFunnel,
"givenName": "Garrett",
"leadId": "48635179",
"leadType": "open-world-fine-like-itself",
"nationalId": "30562255",
"number": "doctor-stop-particular-actually-form",
"phoneNumber": "respond-serious-white-our-social",
"stage": "fact-senior-trouble-reach-they"
}
}
}
leads
Type: LeadsConnection
URL: https://api.octopus.energy/v1/graphql/
Fetch all leads for this Kraken, with optional filtering.
Query Complexity: 3
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
Input fields for retrieving leads. |
|
|
|
Query
query Leads(
$after: String,
$before: String,
$first: Int,
$input: LeadsQueryInput,
$last: Int,
$offset: Int
) {
leads(
after: $after,
before: $before,
first: $first,
input: $input,
last: $last,
offset: $offset
) {
edgeCount
edges {
...LeadsEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"input": LeadsQueryInput,
"last": 10,
"offset": 26
}
leaveSupplierProcess
Type: LeaveSupplierProcessType
URL: https://api.octopus.energy/v1/graphql/
Details associated with a LeaveSupplier process.
Query Complexity: 1
Possible Errors:
- KT-CT-10302: Invalid data.
- KT-CT-10333: Missing either number of leave supplier process id.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access third party queries
OR Can query lifecycle processes
Arguments
| Name | Description |
|---|---|
|
The leave supplier process ID. |
|
The leave supplier process number, e.g. LS-12345678. |
Query
query LeaveSupplierProcess($number: String) {
leaveSupplierProcess(number: $number) {
id
number
stage
status
subtype
supplyPoints {
...SupplyPointConnectionTypeConnectionFragment
}
}
}
Variables
{
"number": "player-mean-machine-begin-civil"
}
Response
{
"data": {
"leaveSupplierProcess": {
"id": "42364592",
"number": "effort-off-save-kid-forward",
"stage": "ability-series-major-trip-American",
"status": "PENDING",
"subtype": "music-agent-something-true-before",
"supplyPoints": SupplyPointConnectionTypeConnection
}
}
}
legacyOrderDetails
Type: LegacyOrderDetailsType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-13101: Order not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Order identifier. |
Query
query LegacyOrderDetails($identifier: String!) {
legacyOrderDetails(identifier: $identifier) {
order {
...LegacyOrderTypeFragment
}
resources {
...LegacyOrderResourceFragment
}
status
}
}
Variables
{
"identifier": "40675922"
}
Response
{
"data": {
"legacyOrderDetails": {
"order": LegacyOrderType,
"resources": [LegacyOrderResource],
"status": "PENDING"
}
}
}
lifecycleProcesses
Type: LifecycleProcessesType
URL: https://api.octopus.energy/v1/graphql/
Get all lifecycle processes associated with an account.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query lifecycle processes
Arguments
| Name | Description |
|---|---|
|
The account number, e.g. A-12345678. |
|
A flag to filter out only active/current processes. |
|
The chronological order in which the lifecycle processes are sorted. |
Query
query LifecycleProcesses(
$accountNumber: String!,
$onlyActive: Boolean,
$sortOrder: LifecycleProcessesSortOrder
) {
lifecycleProcesses(
accountNumber: $accountNumber,
onlyActive: $onlyActive,
sortOrder: $sortOrder
) {
joinSupplierProcesses {
...JoinSupplierProcessConnectionTypeConnectionFragment
}
leavePropertyProcesses {
...LeavePropertyProcessConnectionTypeConnectionFragment
}
leaveSupplierProcesses {
...LeaveSupplierProcessConnectionTypeConnectionFragment
}
occupyPropertyProcesses {
...OccupyPropertyProcessConnectionTypeConnectionFragment
}
}
}
Variables
{
"accountNumber": "A-C88C2483",
"onlyActive": true,
"sortOrder": "ASC"
}
Response
{
"data": {
"lifecycleProcesses": {
"joinSupplierProcesses": JoinSupplierProcessConnectionTypeConnection,
"leavePropertyProcesses": LeavePropertyProcessConnectionTypeConnection,
"leaveSupplierProcesses": LeaveSupplierProcessConnectionTypeConnection,
"occupyPropertyProcesses": OccupyPropertyProcessConnectionTypeConnection
}
}
}
livePaymentAdequacy
Type: LivePaymentAdequacyQuery
URL: https://api.octopus.energy/v1/graphql/
Get up to date payment adequacy data.
Query Complexity: 1
Possible Errors:
- KT-CT-3822: Unauthorized.
- KT-CT-3922: Ledger not found for the account.
- KT-CT-3923: Unauthorized.
- KT-GB-3915: Could not calculate current PA data.
- KT-GB-3916: No statement in last 60 days.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
|
Ledger number. |
|
Payment adequacy policy ID. If this argument is |
Query
query LivePaymentAdequacy(
$accountNumber: String!,
$ledgerNumber: String,
$policyId: String
) {
livePaymentAdequacy(
accountNumber: $accountNumber,
ledgerNumber: $ledgerNumber,
policyId: $policyId
) {
currentBalance
estimatedConsumption {
...ConsumptionBreakdownFragment
}
recommendedPayment {
...PaymentBreakdownFragment
}
reviewedOn
targetBalance
}
}
Variables
{
"accountNumber": "A-FE13A99D",
"ledgerNumber": "grow-television-establish-dog-every",
"policyId": "79959367"
}
Response
{
"data": {
"livePaymentAdequacy": {
"currentBalance": 47,
"estimatedConsumption": [ConsumptionBreakdown],
"recommendedPayment": PaymentBreakdown,
"reviewedOn": "2012-11-21",
"targetBalance": 6
}
}
}
livePaymentAdequacyCalculation
Type: LivePaymentAdequacyCalculation
URL: https://api.octopus.energy/v1/graphql/
Get payment adequacy data with an up to date calculation.
Query Complexity: 6
Possible Errors:
- KT-CT-3963: Could not calculate live PA data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken ledger number. |
Query
query LivePaymentAdequacyCalculation($ledgerNumber: String!) {
livePaymentAdequacyCalculation(ledgerNumber: $ledgerNumber) {
averageMonthlyCharge
balanceAdjustment
consumption {
...ConsumptionBreakdownConnectionTypeConnectionFragment
}
currentBalance
existingMonthlyAmount
reviewedOn
suggestedNewMonthlyAmount
targetBalance
}
}
Variables
{
"ledgerNumber": "thing-really-lawyer-put-keep"
}
Response
{
"data": {
"livePaymentAdequacyCalculation": {
"averageMonthlyCharge": 98,
"balanceAdjustment": 39,
"consumption": ConsumptionBreakdownConnectionTypeConnection,
"currentBalance": 49,
"existingMonthlyAmount": 28,
"reviewedOn": "2012-07-04",
"suggestedNewMonthlyAmount": 2,
"targetBalance": 65
}
}
}
loyaltyCards
Type: [LoyaltyCardType]
URL: https://api.octopus.energy/v1/graphql/
Get all loyalty cards for the given account user.
Query Complexity: 1
Possible Errors:
- KT-CT-5412: No account user exists with the given id.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Account user id. |
Query
query LoyaltyCards($accountUserId: String!) {
loyaltyCards(accountUserId: $accountUserId) {
id
number
scheme
status
}
}
Variables
{
"accountUserId": "27161513"
}
Response
{
"data": {
"loyaltyCards": [
{
"id": "52067234",
"number": "sit-alone-majority-still-girl",
"scheme": "to-hundred-article-thank-research",
"status": "each-check-fact-bag-act"
}
]
}
}
loyaltyPointLedgerEntry
Type: LoyaltyPointLedgerEntryType
URL: https://api.octopus.energy/v1/graphql/
Resolve a loyalty point ledger entry.
Query Complexity: 1
Possible Errors:
- KT-CT-9215: Loyalty points balance query disabled.
- KT-CT-9223: Loyalty points ledger entry not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query loyalty points ledger entry
Arguments
| Name | Description |
|---|---|
|
Query
query LoyaltyPointLedgerEntry($input: LoyaltyPointLedgerEntryInput!) {
loyaltyPointLedgerEntry(input: $input) {
accountNumber
balanceBroughtForward
balanceCarriedForward
id
idempotencyKey
ledgerType
postedAt
reasonCode
value
}
}
Variables
{
"input": LoyaltyPointLedgerEntryInput
}
Response
{
"data": {
"loyaltyPointLedgerEntry": {
"accountNumber": "A-810C9793",
"balanceBroughtForward": "trial-body-prove-campaign-probably",
"balanceCarriedForward": "say-fund-charge-arm-care",
"id": "28372168",
"idempotencyKey": "7572f1af-6f49-466f-af90-a3e6bc62183d",
"ledgerType": "common-decide-until-state-pay",
"postedAt": "1971-08-31T14:23:09.510538+00:00",
"reasonCode": "rock-continue-child-word-indicate",
"value": "who-project-eight-listen-understand"
}
}
}
loyaltyPointLedgers
Type: [LoyaltyPointLedgerEntryType]
URL: https://api.octopus.energy/v1/graphql/
Get the Loyalty Point ledger entries for the passed user.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query loyalty points ledger entry
Arguments
| Name | Description |
|---|---|
|
The input object for retrieving a loyalty point ledger entry. |
Query
query LoyaltyPointLedgers($input: LoyaltyPointLedgersInput) {
loyaltyPointLedgers(input: $input) {
accountNumber
balanceBroughtForward
balanceCarriedForward
id
idempotencyKey
ledgerType
postedAt
reasonCode
value
}
}
Variables
{
"input": LoyaltyPointLedgersInput
}
Response
{
"data": {
"loyaltyPointLedgers": [
{
"accountNumber": "A-240DFF73",
"balanceBroughtForward": "within-debate-character-evidence-movie",
"balanceCarriedForward": "finish-since-reach-thousand-more",
"id": "67612400",
"idempotencyKey": "13d6cca3-cc06-4503-b724-cbf2ebe6ee41",
"ledgerType": "news-human-huge-every-white",
"postedAt": "2018-12-29T23:16:21.057622+00:00",
"reasonCode": "fast-necessary-look-leader-else",
"value": "scene-reality-check-yeah-various"
}
]
}
}
loyaltyPointsBalance
Type: AccountLoyaltyPointsType
URL: https://api.octopus.energy/v1/graphql/
Get the loyalty points balance for an account.
Query Complexity: 1
Possible Errors:
- KT-CT-9215: Loyalty points balance query disabled.
- KT-CT-9216: Unauthorized.
- KT-CT-9217: Unauthorized.
- KT-CT-9218: Unauthorized.
- KT-CT-9222: Loyalty points balance query requires either accountNumber field (deprecated) or input object (preferred) with account number and optional account user id.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query loyalty points balance
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
Query
query LoyaltyPointsBalance($input: LoyaltyPointsBalanceInput) {
loyaltyPointsBalance(input: $input) {
loyaltyPoints
totalMonetaryAmount
}
}
Variables
{
"input": LoyaltyPointsBalanceInput
}
Response
{
"data": {
"loyaltyPointsBalance": {
"loyaltyPoints": 32,
"totalMonetaryAmount": 10
}
}
}
mcsInstallations
Type: [MCSInstallationType]!
URL: https://api.octopus.energy/v1/graphql/
Look up MCS installation data by certificate number or import MPAN.
Query Complexity: 5
Possible Errors:
- KT-GB-4505: The provided MCS certificate number is not valid.
- KT-GB-4508: The MCS API is currently unavailable.
- KT-GB-4509: Your system is not configured to fetch data from the MCS API, please contact support.
- KT-GB-4510: Exactly one of certificateNumber or importMpan must be provided.
- KT-GB-4511: Your system is not configured to fetch data from the MCS API in this way, please contact support.
- KT-GB-4512: The provided MPAN is not valid.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query mcs api
Arguments
| Name | Description |
|---|---|
|
The MCS certificate number to look up. |
|
The import MPAN to look up. |
Query
query McsInstallations(
$certificateNumber: String,
$importMpan: String
) {
mcsInstallations(
certificateNumber: $certificateNumber,
importMpan: $importMpan
) {
addressLine1
addressLine2
addressLine3
certificateNumber
commissioningDate
county
countyDescription
createdDate
declaredNetCapacity
dnoNotificationCompliance
dnoNotificationComplianceDescription
estimatedAnnualGeneration
generationMeterReading
generationMeterSerialNumber
installationType
installationTypeDescription
mpan
postcode
status
statusDescription
technology
technologyDescription
totalCapacity
}
}
Variables
{
"certificateNumber": "maybe-return-plan-surface-focus",
"importMpan": "tend-skill-fish-job-note"
}
Response
{
"data": {
"mcsInstallations": [
{
"addressLine1": "future-magazine-suddenly-join-project",
"addressLine2": "others-blue-east-this-smile",
"addressLine3": "a-coach-case-right-western",
"certificateNumber": "involve-debate-research-game-spend",
"commissioningDate": "1999-05-10",
"county": 44,
"countyDescription": "never-special-month-couple-enter",
"createdDate": "1993-07-20T13:34:37.915549+00:00",
"declaredNetCapacity": 484.64,
"dnoNotificationCompliance": 100,
"dnoNotificationComplianceDescription": "defense-by-white-believe-offer",
"estimatedAnnualGeneration": 346.13,
"generationMeterReading": "might-American-how-month-hear",
"generationMeterSerialNumber": "national-attack-system-step-season",
"installationType": "city-represent-mean-tell-hospital",
"installationTypeDescription": "only-offer-industry-nor-fly",
"mpan": "beyond-respond-contain-away-better",
"postcode": "phone-subject-single-a-father",
"status": 12,
"statusDescription": "guess-involve-guess-make-those",
"technology": 70,
"technologyDescription": "item-tell-seven-condition-benefit",
"totalCapacity": 490.92
}
]
}
}
message
Type: Message!
URL: https://api.octopus.energy/v1/graphql/
Get the details of a transactional message with a given external ID.
Query Complexity: 1
Possible Errors:
- KT-CT-9911: Message not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ID of the transactional message. |
Query
query Message($messageId: ID!) {
message(messageId: $messageId) {
account {
...AccountTypeFragment
}
accountUser {
...AccountUserTypeFragment
}
channel
dispatchedAt
failedAt
id
}
}
Variables
{
"messageId": "29049923"
}
Response
{
"data": {
"message": {
"account": AccountType,
"accountUser": AccountUserType,
"channel": "EMAIL",
"dispatchedAt": "2017-10-18T01:50:58.356997+00:00",
"failedAt": "1998-10-18T05:07:35.405005+00:00",
"id": "92198804"
}
}
}
metadata
Type: [Metadata]
URL: https://api.octopus.energy/v1/graphql/
Metadata for a linked object.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
- KT-CT-4124: Unauthorized.
- KT-CT-4177: Unauthorized.
- KT-CT-6622: Unauthorized.
- KT-CT-6637: Unauthorized.
- KT-CT-8411: Invalid data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query metadata
Arguments
| Name | Description |
|---|---|
|
|
|
Query
query Metadata(
$identifier: String!,
$linkedObjectType: LinkedObjectType
) {
metadata(
identifier: $identifier,
linkedObjectType: $linkedObjectType
) {
key
value
}
}
Variables
{
"identifier": "62840949",
"linkedObjectType": "ACCOUNT"
}
Response
{
"data": {
"metadata": [
{
"key": "save-impact-age-concern-six",
"value": {"key": "value"}
}
]
}
}
metadataForKey
Type: Metadata
URL: https://api.octopus.energy/v1/graphql/
Metadata for a linked object with key.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
- KT-CT-4124: Unauthorized.
- KT-CT-4155: Invalid data.
- KT-CT-4177: Unauthorized.
- KT-CT-4179: No metadata found with given key.
- KT-CT-6622: Unauthorized.
- KT-CT-6637: Unauthorized.
- KT-CT-8411: Invalid data.
- KT-CT-8416: No metadata found with given key.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query metadata
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Query
query MetadataForKey(
$identifier: String!,
$key: String!,
$linkedObjectType: LinkedObjectType
) {
metadataForKey(
identifier: $identifier,
key: $key,
linkedObjectType: $linkedObjectType
) {
key
value
}
}
Variables
{
"identifier": "11029955",
"key": "hundred-describe-positive-brother-about",
"linkedObjectType": "ACCOUNT"
}
Response
{
"data": {
"metadataForKey": {
"key": "buy-compare-ever-sea-visit",
"value": {"key": "value"}
}
}
}
meterPoints
Type: MeterPointInterface
URL: https://api.octopus.energy/v1/graphql/
Get a meter point via it's associated mpan or mprn.
Query Complexity: 1
Possible Errors:
- KT-CT-4011: No meter points found with the given ID.
- KT-GB-5601: One of either MPAN or MPRN must be provided.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The MPAN for the electricity meterpoint to return. |
|
The MPRN for the gas meterpoint to return. |
Query
query MeterPoints(
$mpan: ID,
$mprn: ID
) {
meterPoints(
mpan: $mpan,
mprn: $mprn
) {
enrolment {
...EnrolmentTypeFragment
}
meters {
...MeterFragment
}
status
}
}
Variables
{
"mpan": "45835531",
"mprn": "25478402"
}
Response
{
"data": {
"meterPoints": {
"enrolment": EnrolmentType,
"meters": Meter,
"status": "TV-local-provide-pick-between"
}
}
}
mfaDevices
Type: [MfaDevice]
URL: https://api.octopus.energy/v1/graphql/
Get all MFA devices for the current user.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query MfaDevices {
mfaDevices {
deviceType
isConfirmed
}
}
Response
{
"data": {
"mfaDevices": [
{
"deviceType": "top-brother-some-seek-give",
"isConfirmed": true
}
]
}
}
multipleElectricityMeterPointsForAddress
Type: ElectricityMeterPointForAddressType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-GB-6612: We couldn't find a match for this address. Please verify it and try again.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Query
query MultipleElectricityMeterPointsForAddress(
$address: AddressSearchType,
$searchDomesticOnly: Boolean,
$useDes: Boolean
) {
multipleElectricityMeterPointsForAddress(
address: $address,
searchDomesticOnly: $searchDomesticOnly,
useDes: $useDes
) {
addressHasMoreThanOneElectricityMeterPoint
addressLine1
addressLine2
electricityMeterPoints
postcode
}
}
Variables
{
"address": AddressSearchType,
"searchDomesticOnly": true,
"useDes": true
}
Response
{
"data": {
"multipleElectricityMeterPointsForAddress": {
"addressHasMoreThanOneElectricityMeterPoint": true,
"addressLine1": "want-picture-tend-direction-film",
"addressLine2": "capital-perhaps-sister-here-wait",
"electricityMeterPoints": "indicate-light-stock-goal-right",
"postcode": "consider-also-all-store-sing"
}
}
}
node
Type: Node
URL: https://api.octopus.energy/v1/graphql/
Represents an individual object/resource in the API.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ID of the object |
Query
query Node($id: ID!) {
node(id: $id) {
id
}
}
Variables
{
"id": "98343762"
}
Response
{
"data": {
"node": {
"id": "74362858"
}
}
}
occupierAccount
Type: OccupierAccount
URL: https://api.octopus.energy/v1/graphql/
Looks up an occupier account based on postcode and optionally their last 4 digits of the account number.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['5/m'] |
Arguments
| Name | Description |
|---|---|
|
The postcode to search for. |
|
Optional - the last 4 digits of the account number. |
Query
query OccupierAccount(
$postcode: String!,
$shortcode: String
) {
occupierAccount(
postcode: $postcode,
shortcode: $shortcode
) {
account
address
date
occupyToken
propertyId
}
}
Variables
{
"postcode": "notice-suffer-environment-bit-seat",
"shortcode": "various-approach-write-teach-entire"
}
Response
{
"data": {
"occupierAccount": {
"account": "pressure-job-eight-travel-three",
"address": "behind-air-item-his-fight",
"date": "single-defense-need-rate-street",
"occupyToken": "example-apply-relationship-moment-thank",
"propertyId": 63633121
}
}
}
occupierAccounts
Type: [OccupierAccount]
URL: https://api.octopus.energy/v1/graphql/
Looks up all occupier accounts for a postcode and optionally their last 4 digits of the account number.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['5/m'] |
Arguments
| Name | Description |
|---|---|
|
The postcode to search for. |
|
Optional - the last 4 digits of the account number. |
Query
query OccupierAccounts(
$postcode: String!,
$shortcode: String
) {
occupierAccounts(
postcode: $postcode,
shortcode: $shortcode
) {
account
address
date
occupyToken
propertyId
}
}
Variables
{
"postcode": "name-cut-within-everybody-resource",
"shortcode": "section-get-administration-win-animal"
}
Response
{
"data": {
"occupierAccounts": [
{
"account": "stock-hard-eat-memory-section",
"address": "story-reflect-like-when-eight",
"date": "pick-huge-run-area-opportunity",
"occupyToken": "find-interesting-themselves-letter-when",
"propertyId": 60137041
}
]
}
}
ocppConnection
Type: OCPPConnectionType
URL: https://api.octopus.energy/v1/graphql/
To confirm whether a device is connected to OCPP.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4311: Unable to confirm OCPP connection.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Query
query OcppConnection($accountNumber: String!) {
ocppConnection(accountNumber: $accountNumber) {
isConnected
}
}
Variables
{
"accountNumber": "A-A9247074"
}
Response
{
"data": {
"ocppConnection": {
"isConnected": true
}
}
}
ocppDetails
Type: OCPPDetailsType
URL: https://api.octopus.energy/v1/graphql/
The user specific generated OCPP details.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Query
query OcppDetails($accountNumber: String!) {
ocppDetails(accountNumber: $accountNumber) {
url
username
}
}
Variables
{
"accountNumber": "A-39316F71"
}
Response
{
"data": {
"ocppDetails": {
"url": "part-laugh-bit-place-speak",
"username": "find-dream-bar-physical-anything"
}
}
}
octocareOnboardingInfo
Type: OctocareOnboardingInfo
URL: https://api.octopus.energy/v1/graphql/
Returns the info required to start the onboarding process for a Mini in the cared-for account's property, by the cared.
Query Complexity: 1
Possible Errors:
- KT-GB-10501: Account is not currently supported.
- KT-GB-10502: Account is not yet enrolled.
- KT-GB-10503: Incorrect number of communication hubs.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can view octocare onboarding info
Deprecated
The 'octocareOnboardingInfo' field is deprecated.
The octocare feature is no longer supported.
- Marked as deprecated on 2026-04-22.
- Scheduled for removal on or after 2026-05-22.
Arguments
| Name | Description |
|---|---|
|
Cared-for account number. |
Query
query OctocareOnboardingInfo($accountNumber: String!) {
octocareOnboardingInfo(accountNumber: $accountNumber) {
chfDeviceId
propertyAddressLine1
propertyId
}
}
Variables
{
"accountNumber": "A-420AD9AA"
}
Response
{
"data": {
"octocareOnboardingInfo": {
"chfDeviceId": "55205096",
"propertyAddressLine1": "skin-nation-strategy-future-about",
"propertyId": "91431519"
}
}
}
octocareUsageInfo
Type: OctocareUsageInfo
URL: https://api.octopus.energy/v1/graphql/
Returns the info required to request and display live usage information for the cared-for account meter: the meter device ID and 1st address line of the property.
Query Complexity: 1
Possible Errors:
- KT-GB-10501: Account is not currently supported.
- KT-GB-10502: Account is not yet enrolled.
- KT-GB-10503: Incorrect number of communication hubs.
- KT-GB-10504: Property is not currently supported.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'octocareUsageInfo' field is deprecated.
The octocare feature is no longer supported.
- Marked as deprecated on 2026-04-22.
- Scheduled for removal on or after 2026-05-22.
Arguments
| Name | Description |
|---|---|
|
Cared-for account number. |
Query
query OctocareUsageInfo($accountNumber: String!) {
octocareUsageInfo(accountNumber: $accountNumber) {
meterDeviceId
propertyAddressLine1
}
}
Variables
{
"accountNumber": "A-10F37D20"
}
Response
{
"data": {
"octocareUsageInfo": {
"meterDeviceId": "41051461",
"propertyAddressLine1": "science-something-lose-knowledge-report"
}
}
}
octoHeatPumpControllerConfiguration
Type: ControllerAndZoneConfiguration
URL: https://api.octopus.energy/v1/graphql/
Heat pump controller, zones and sensor configuration.
Query Complexity: 2
Possible Errors:
- KT-CT-4305: Unable to fetch heating controller configuration.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'heatPumpControllerConfiguration' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Query
query OctoHeatPumpControllerConfiguration(
$accountNumber: String!,
$euid: ID!
) {
octoHeatPumpControllerConfiguration(
accountNumber: $accountNumber,
euid: $euid
) {
controller {
...ControllerConfigurationFragment
}
heatPump {
...HeatPumpConfigurationFragment
}
zones {
...ZoneInformationFragment
}
}
}
Variables
{
"accountNumber": "A-A1DE0A10",
"euid": "74799345"
}
Response
{
"data": {
"octoHeatPumpControllerConfiguration": {
"controller": ControllerConfiguration,
"heatPump": HeatPumpConfiguration,
"zones": [ZoneInformation]
}
}
}
octoHeatPumpControllerEuids
Type: [String]
URL: https://api.octopus.energy/v1/graphql/
Heat pump controller EUIDs associated with an account.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'controllerEuids' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Arguments
| Name | Description |
|---|---|
|
Query
query OctoHeatPumpControllerEuids($accountNumber: String) {
octoHeatPumpControllerEuids(accountNumber: $accountNumber)
}
Variables
{
"accountNumber": "A-9469C71D"
}
Response
{
"data": {
"octoHeatPumpControllerEuids": "fire-action-report-hit-expert"
}
}
octoHeatPumpControllersAtLocation
Type: [ControllerAtLocation]
URL: https://api.octopus.energy/v1/graphql/
Heat pump controllers attached to an account at a given location.
Query Complexity: 1
Possible Errors:
- KT-CT-3823: Unauthorized.
- KT-CT-4305: Unable to fetch heating controller configuration.
- KT-CT-6622: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'octoHeatPumpControllersAtLocation' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Query
query OctoHeatPumpControllersAtLocation(
$accountNumber: String!,
$propertyId: ID!
) {
octoHeatPumpControllersAtLocation(
accountNumber: $accountNumber,
propertyId: $propertyId
) {
controller {
...ControllerFragment
}
heatPumpModel
location {
...LocationFragment
}
provisionedAt
}
}
Variables
{
"accountNumber": "A-42F34ED1",
"propertyId": "93879978"
}
Response
{
"data": {
"octoHeatPumpControllersAtLocation": [
{
"controller": Controller,
"heatPumpModel": "what-collection-effect-design-of",
"location": Location,
"provisionedAt": "1985-09-24T16:55:07.339051+00:00"
}
]
}
}
octoHeatPumpControllerStatus
Type: ControllerStatus
URL: https://api.octopus.energy/v1/graphql/
Retrieve the heat pump controller device status.
Query Complexity: 2
Possible Errors:
- KT-CT-4303: Unable to fetch device status.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'heatPumpControllerStatus' field is deprecated.
This query has been migrated to Octopus Energy backend. Please see https://api.backend.octopus.energy/v1/graphql.
- Marked as deprecated on 2026-03-18.
- Scheduled for removal on or after 2026-04-30.
Query
query OctoHeatPumpControllerStatus(
$accountNumber: String!,
$euid: ID!
) {
octoHeatPumpControllerStatus(
accountNumber: $accountNumber,
euid: $euid
) {
sensors {
...SensorStatusFragment
}
zones {
...ZoneStatusFragment
}
}
}
Variables
{
"accountNumber": "A-BFDF34D9",
"euid": "88238116"
}
Response
{
"data": {
"octoHeatPumpControllerStatus": {
"sensors": [SensorStatus],
"zones": [ZoneStatus]
}
}
}
octoplusAccountInfo
Type: OctoplusAccountInfoType
URL: https://api.octopus.energy/v1/graphql/
Octoplus information for a given account.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken account number. |
Query
query OctoplusAccountInfo($accountNumber: String!) {
octoplusAccountInfo(accountNumber: $accountNumber) {
enrollmentStatus
isLoyaltyPointsUser
octoplusEligibility {
...OctoplusEligibilityTypeFragment
}
octoplusSnapWebUrl {
...OctoplusSnapWebUrlTypeFragment
}
shouldUseV2
}
}
Variables
{
"accountNumber": "A-947CB5AC"
}
Response
{
"data": {
"octoplusAccountInfo": {
"enrollmentStatus": "ENROLLED",
"isLoyaltyPointsUser": true,
"octoplusEligibility": OctoplusEligibilityType,
"octoplusSnapWebUrl": OctoplusSnapWebUrlType,
"shouldUseV2": true
}
}
}
octoplusFeatureFlags
Type: OctoplusFeatureFlagsType
URL: https://api.octopus.energy/v1/graphql/
Feature flags for the octoplus campaign.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query OctoplusFeatureFlags {
octoplusFeatureFlags {
shouldClientDisplayOctoplus
shouldClientDisplayOctoplusPartnerOfferList
shouldClientDisplayOctoplusPartnerOffers
shouldClientDisplayOctoplusRewards
shouldClientDisplayOctoplusShoptopusOffers
shouldClientDisplayOctopointsV2
}
}
Response
{
"data": {
"octoplusFeatureFlags": {
"shouldClientDisplayOctoplus": true,
"shouldClientDisplayOctoplusPartnerOfferList": true,
"shouldClientDisplayOctoplusPartnerOffers": true,
"shouldClientDisplayOctoplusRewards": true,
"shouldClientDisplayOctoplusShoptopusOffers": true,
"shouldClientDisplayOctopointsV2": true
}
}
}
octoplusOfferGroups
Type: OctoplusOfferGroupConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Octoplus Offer Groups available for a given account_user and account combination.
Query Complexity: 1
Possible Errors:
- KT-GB-9319: This feature is not currently available.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'octoplusOfferGroups' field is deprecated.
The Octoplus feature is going through changes. This query is no longer available.
- Marked as deprecated on 2026-02-10.
- Scheduled for removal on or after 2026-08-10.
Arguments
| Name | Description |
|---|---|
|
Account number for the Octoplus-enrolled account. |
|
|
|
|
|
|
|
ID of the Offer Group being queried. |
|
Query
query OctoplusOfferGroups(
$accountNumber: String!,
$after: String,
$before: String,
$first: Int,
$id: Int,
$last: Int
) {
octoplusOfferGroups(
accountNumber: $accountNumber,
after: $after,
before: $before,
first: $first,
id: $id,
last: $last
) {
edgeCount
edges {
...OctoplusOfferGroupConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-9B8F9637",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"id": 88088327,
"last": 10
}
Response
{
"data": {
"octoplusOfferGroups": {
"edgeCount": 92,
"edges": [OctoplusOfferGroupConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 52
}
}
}
octoplusOffers
Type: [OctoplusOfferType]
URL: https://api.octopus.energy/v1/graphql/
Octoplus Offers available for a given account_user and account combination.
Query Complexity: 1
Possible Errors:
- KT-GB-9319: This feature is not currently available.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'octoplusOffers' field is deprecated.
The Octoplus feature is going through changes. This query is no longer available.
- Marked as deprecated on 2026-02-10.
- Scheduled for removal on or after 2026-08-10.
Arguments
| Name | Description |
|---|---|
|
Account number for the Octoplus-enrolled account. |
|
Slug of the offer being queried. |
Query
query OctoplusOffers(
$accountNumber: String!,
$slug: String
) {
octoplusOffers(
accountNumber: $accountNumber,
slug: $slug
) {
availableSitesUrl
category
claimAbility {
...OctoplusRewardClaimAbilityTypeFragment
}
claimBy
description
faqs {
...OctoplusOfferFAQsTypeFragment
}
imageUrls {
...OctoplusOfferImageUrlsTypeFragment
}
longDescription
name
partnerName
partnerSiteUrl
pointsCost
priceTag
slug
termsAndConditions
usageInstructions
}
}
Variables
{
"accountNumber": "A-A777F885",
"slug": "husband-off-part-ten-respond"
}
Response
{
"data": {
"octoplusOffers": [
{
"availableSitesUrl": "difficult-throw-story-many-almost",
"category": "may-perhaps-forward-interesting-child",
"claimAbility": OctoplusRewardClaimAbilityType,
"claimBy": "1978-03-15T13:22:43.306575+00:00",
"description": "support-final-somebody-table-enough",
"faqs": [OctoplusOfferFAQsType],
"imageUrls": OctoplusOfferImageUrlsType,
"longDescription": "partner-almost-yeah-list-media",
"name": "population-be-support-back-indicate",
"partnerName": "usually-visit-live-sort-none",
"partnerSiteUrl": "source-indeed-wide-son-while",
"pointsCost": 84,
"priceTag": "mention-Mrs-have-writer-some",
"slug": "do-degree-buy-system-factor",
"termsAndConditions": "nor-safe-cost-section-style",
"usageInstructions": "information-camera-question-should-some"
}
]
}
}
octoplusRewards
Type: [OctoplusRewardType]
URL: https://api.octopus.energy/v1/graphql/
Octoplus Rewards for a given account user.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-GB-9319: This feature is not currently available.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'octoplusRewards' field is deprecated.
The Octoplus feature is going through changes. This query is no longer available.
- Marked as deprecated on 2026-02-10.
- Scheduled for removal on or after 2026-08-10.
Arguments
| Name | Description |
|---|---|
|
Account number for the Octoplus-enrolled account. |
|
Slug of the offer being queried. |
|
Id for the reward being queried. |
Query
query OctoplusRewards(
$accountNumber: String,
$offerSlug: String,
$rewardId: Int
) {
octoplusRewards(
accountNumber: $accountNumber,
offerSlug: $offerSlug,
rewardId: $rewardId
) {
accountNumber
claimedAt
id
offer {
...OctoplusOfferTypeFragment
}
status
vouchers {
... on OctoplusVoucherType {
...OctoplusVoucherTypeFragment
}
... on ShoptopusVoucherType {
...ShoptopusVoucherTypeFragment
}
}
}
}
Variables
{
"accountNumber": "A-A069F993",
"offerSlug": "consumer-have-single-condition-degree",
"rewardId": 67293041
}
Response
{
"data": {
"octoplusRewards": [
{
"accountNumber": "A-D2CFE74C",
"claimedAt": "2013-09-02T15:42:46.358163+00:00",
"id": 11908706,
"offer": OctoplusOfferType,
"status": "PENDING",
"vouchers": OctoplusVoucherType
}
]
}
}
offerForQuoting
Type: OfferType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can create quoting offer group
Arguments
| Name | Description |
|---|---|
|
The identifier of the offer to query. |
Query
query OfferForQuoting($identifier: ID) {
offerForQuoting(identifier: $identifier) {
acceptedAt
createdBy {
...ActorTypeFragment
}
description
identifier
quote {
...QuoteType_Fragment
}
rejectedAt
validFrom
validTo
}
}
Variables
{
"identifier": "83525657"
}
Response
{
"data": {
"offerForQuoting": {
"acceptedAt": "1982-02-13T21:36:34.906063+00:00",
"createdBy": ActorType,
"description": "suggest-available-now-because-activity",
"identifier": "61608396",
"quote": QuoteType_,
"rejectedAt": "2024-05-02T11:36:25.060865+00:00",
"validFrom": "2016-09-07T01:38:30.174224+00:00",
"validTo": "1991-09-01T11:09:59.528508+00:00"
}
}
}
offerGroupForQuoting
Type: OfferGroupType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can create quoting offer group
Arguments
| Name | Description |
|---|---|
|
The identifier of the offer group to query. |
Query
query OfferGroupForQuoting($identifier: ID) {
offerGroupForQuoting(identifier: $identifier) {
createdAt
createdBy {
...ActorTypeFragment
}
identifier
offers {
...OfferTypeFragment
}
}
}
Variables
{
"identifier": "24074109"
}
offering
Type: OfferingType
URL: https://api.octopus.energy/v1/graphql/
Get details about a product offering.
Query Complexity: 1
Possible Errors:
- KT-CT-12001: Product catalogue offering with given identifier not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query catalog offerings
Arguments
| Name | Description |
|---|---|
|
The identifier of the offering to query. |
Query
query Offering($identifier: String) {
offering(identifier: $identifier) {
customerDescription
customerName
groups {
...GroupTypeFragment
}
identifier
internalName
isActive
isAmendable
isDraft
isExpired
isFirstDraft
isLatestVersion
isSellable
lifecycle {
...LifecycleTypeFragment
}
offeringComponents {
...OfferingComponentTypeFragment
}
productComponents {
...ProductComponentTypeFragment
}
tags {
...TagTypeFragment
}
termTemplateComponents {
...TermTemplateComponentTypeFragment
}
}
}
Variables
{
"identifier": "55291134"
}
Response
{
"data": {
"offering": {
"customerDescription": "pretty-direction-wait-order-measure",
"customerName": "painting-couple-field-provide-return",
"groups": [GroupType],
"identifier": "20155296",
"internalName": "skin-guy-if-eight-system",
"isActive": true,
"isAmendable": true,
"isDraft": true,
"isExpired": true,
"isFirstDraft": true,
"isLatestVersion": true,
"isSellable": true,
"lifecycle": LifecycleType,
"offeringComponents": [OfferingComponentType],
"productComponents": [ProductComponentType],
"tags": [TagType],
"termTemplateComponents": [TermTemplateComponentType]
}
}
}
opportunities
Type: OpportunitiesConnection
URL: https://api.octopus.energy/v1/graphql/
Fetch all opportunities for this Kraken, with optional filtering.
Query Complexity: 3
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
Input fields for retrieving opportunities. |
|
|
|
Query
query Opportunities(
$after: String,
$before: String,
$first: Int,
$input: OpportunitiesQueryInput,
$last: Int,
$offset: Int
) {
opportunities(
after: $after,
before: $before,
first: $first,
input: $input,
last: $last,
offset: $offset
) {
edgeCount
edges {
...OpportunitiesEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"input": OpportunitiesQueryInput,
"last": 10,
"offset": 39
}
Response
{
"data": {
"opportunities": {
"edgeCount": 76,
"edges": [OpportunitiesEdge],
"pageInfo": PageInfo,
"totalCount": 85
}
}
}
opportunityByNumber
Type: OpportunityOutput
URL: https://api.octopus.energy/v1/graphql/
Get opportunity details by number.
Query Complexity: 1
Possible Errors:
- KT-CT-8906: Opportunity not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
Opportunity number identifier. |
Query
query OpportunityByNumber($number: String) {
opportunityByNumber(number: $number) {
assignedToAffiliateNumber
assignedToTeamIdentifier
assignedToUserIdentifier
attachments {
...OpportunityAttachmentFragment
}
consents {
...ConsentOutputFragment
}
email
extraDetailItems {
...ExtraDetailFragment
}
funnel {
...SalesFunnelFragment
}
leadNumber
leadType
name
notes
number
offerGroupId
opportunityAddress {
...AddressOutputFragment
}
opportunityRichAddress {
...RichAddressTypeFragment
}
phoneNumber
productOffering {
...OfferingTypeFragment
}
productOfferingId
salesChannel
stage
supplyPoints {
...LeadSupplyPointTypeFragment
}
}
}
Variables
{
"number": "treatment-box-smile-law-describe"
}
Response
{
"data": {
"opportunityByNumber": {
"assignedToAffiliateNumber": "yes-hear-exist-hear-sing",
"assignedToTeamIdentifier": "76563269",
"assignedToUserIdentifier": "44852743",
"attachments": [OpportunityAttachment],
"consents": [ConsentOutput],
"email": "particularly-mention-budget-management-major",
"extraDetailItems": [ExtraDetail],
"funnel": SalesFunnel,
"leadNumber": "trade-small-foreign-bit-call",
"leadType": "real-long-single-town-option",
"name": "better-fly-she-blue-mother",
"notes": "white-body-common-sort-significant",
"number": "idea-car-soon-player-table",
"offerGroupId": "43409132",
"opportunityAddress": AddressOutput,
"opportunityRichAddress": RichAddressType,
"phoneNumber": "probably-daughter-black-story-rate",
"productOffering": OfferingType,
"productOfferingId": "37318466",
"salesChannel": "itself-sort-century-sea-Mr",
"stage": "score-science-family-exactly-company",
"supplyPoints": [LeadSupplyPointType]
}
}
}
opportunityProductSummary
Type: [OpportunityProductSummary!]!
URL: https://api.octopus.energy/v1/graphql/
Return summaries of all products in opportunity's accepted offer. Supports multi-product offerings like dual fuel.
Query Complexity: 2
Possible Errors:
- KT-CT-8906: Opportunity not found.
- KT-CT-8922: The opportunity does not have an accepted offer.
- KT-CT-8923: The opportunity does not have a linked offer group.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
Opportunity number. |
Query
query OpportunityProductSummary($number: String) {
opportunityProductSummary(number: $number) {
market
productCharacteristics
productCode
productIdentifier
productOfferingIdentifier
}
}
Variables
{
"number": "arrive-forward-model-little-agree"
}
Response
{
"data": {
"opportunityProductSummary": [
{
"market": "remember-crime-certain-traditional-family",
"productCharacteristics": "abc123" | 1 | 1.0 | true | ["abc123"] | AccountType,
"productCode": "whom-anyone-face-town-professor",
"productIdentifier": "56474800",
"productOfferingIdentifier": "43547641"
}
]
}
}
opportunityValueByKey
Type: String
URL: https://api.octopus.energy/v1/graphql/
Get the value of a given key that is stored in an opportunity's related JSONFields.
Query Complexity: 2
Possible Errors:
- KT-CT-8903: Unable to update opportunity.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
The key the a funnel-specific value you wish to obtain. |
|
The identifier of the opportunity to query. |
Query
query OpportunityValueByKey(
$key: String,
$opportunityId: ID
) {
opportunityValueByKey(
key: $key,
opportunityId: $opportunityId
)
}
Variables
{
"key": "measure-decision-fly-already-prepare",
"opportunityId": "82535475"
}
Response
{
"data": {
"opportunityValueByKey": "wide-push-join-next-Democrat"
}
}
partnerTeam
Type: PartnerTeamType
URL: https://api.octopus.energy/v1/graphql/
Return the details of a given partner team.
Query Complexity: 1
Possible Errors:
- KT-CT-7731: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query partner teams
Arguments
| Name | Description |
|---|---|
|
Input object to identify the partner team. |
Query
query PartnerTeam($input: PartnerTeamInput!) {
partnerTeam(input: $input) {
name
number
parentTeamNumber
teamMembers {
...PartnerTeamUserConnectionTypeConnectionFragment
}
}
}
Variables
{
"input": PartnerTeamInput
}
Response
{
"data": {
"partnerTeam": {
"name": "size-hour-type-act-education",
"number": "pay-day-threat-federal-different",
"parentTeamNumber": "Congress-staff-consumer-thought-manager",
"teamMembers": PartnerTeamUserConnectionTypeConnection
}
}
}
partnerUser
Type: PartnerUserType
URL: https://api.octopus.energy/v1/graphql/
Return the details of a given partner user, if any exists.
Query Complexity: 1
Possible Errors:
- KT-CT-7724: Either number or email must be provided.
- KT-CT-7725: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query partner users
Arguments
| Name | Description |
|---|---|
|
The partner user email address. |
|
The partner user number. |
Query
query PartnerUser(
$email: String,
$number: String
) {
partnerUser(
email: $email,
number: $number
) {
createdAt
email
familyName
givenName
id
lastLogin
name
number
organisation {
...AffiliateOrganisationTypeFragment
}
permissions {
...PartnerUserPermissionFragment
}
}
}
Variables
{
"email": "hit-everyone-late-fire-boy",
"number": "should-reason-reduce-begin-enough"
}
Response
{
"data": {
"partnerUser": {
"createdAt": "2018-09-28T12:21:20.918407+00:00",
"email": "act-hotel-as-site-history",
"familyName": "Gilbert",
"givenName": "Brandy",
"id": "30129468",
"lastLogin": "1981-09-12T11:46:53.210670+00:00",
"name": "company-product-prepare-guy-per",
"number": "for-realize-people-hair-customer",
"organisation": AffiliateOrganisationType,
"permissions": [PartnerUserPermission]
}
}
}
partnerViewer
Type: PartnerViewerType
URL: https://api.octopus.energy/v1/graphql/
The currently authenticated partner user.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query PartnerViewer {
partnerViewer {
email
name
number
permissions {
...PartnerViewerPermissionFragment
}
}
}
Response
{
"data": {
"partnerViewer": {
"email": "place-something-pass-realize-future",
"name": "natural-cultural-least-program-common",
"number": "speak-edge-manage-player-color",
"permissions": [PartnerViewerPermission]
}
}
}
passwordValidatorHelpTexts
Type: [String]
URL: https://api.octopus.energy/v1/graphql/
The help text of all configured password validators as plain-text or html. Defaults to plain-text.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Arguments
| Name | Description |
|---|---|
|
Return the results as html instead of plain-text. Defaults to False. |
Query
query PasswordValidatorHelpTexts($asHtml: Boolean) {
passwordValidatorHelpTexts(asHtml: $asHtml)
}
Variables
{
"asHtml": true
}
Response
{
"data": {
"passwordValidatorHelpTexts": "cut-those-travel-century-cover"
}
}
paymentFingerprintChecks
Type: PaymentFingerPrintCheckType
URL: https://api.octopus.energy/v1/graphql/
Check if a given payment fingerprint already exists and/or is risk-listed.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Fingerprint. |
Query
query PaymentFingerprintChecks($fingerprint: String!) {
paymentFingerprintChecks(fingerprint: $fingerprint) {
fingerprint
isFound
isRiskListed
}
}
Variables
{
"fingerprint": "politics-anything-movement-Mrs-explain"
}
Response
{
"data": {
"paymentFingerprintChecks": {
"fingerprint": "bring-movie-prevent-describe-state",
"isFound": true,
"isRiskListed": true
}
}
}
paymentPlanDetails
Type: [PaymentPlanDetails]
URL: https://api.octopus.energy/v1/graphql/
Payment plan details for a given account number.
Query Complexity: 1
Possible Errors:
- KT-CT-3921: Account not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number to retrieve payment plan details for. |
Query
query PaymentPlanDetails($accountNumber: String!) {
paymentPlanDetails(accountNumber: $accountNumber) {
paymentFrequency
paymentFrequencyMultiplier
paymentPlanId
paymentPlanStatus
totalAmountPaid
totalAmountRemaining
totalPlanValue
}
}
Variables
{
"accountNumber": "A-35E6E808"
}
Response
{
"data": {
"paymentPlanDetails": [
{
"paymentFrequency": "ball-how-wife-relate-prevent",
"paymentFrequencyMultiplier": 35,
"paymentPlanId": "19422748",
"paymentPlanStatus": "performance-wall-action-allow-prove",
"totalAmountPaid": 67013217,
"totalAmountRemaining": 92,
"totalPlanValue": 98
}
]
}
}
paymentRequests
Type: PaymentRequestsType
URL: https://api.octopus.energy/v1/graphql/
Get all payment requests for the given ledger.
Query Complexity: 6
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Kraken ledger number. |
Query
query PaymentRequests($ledgerNumber: String!) {
paymentRequests(ledgerNumber: $ledgerNumber) {
paymentRequest {
...PaymentRequestConnectionTypeConnectionFragment
}
}
}
Variables
{
"ledgerNumber": "impact-especially-heavy-management-spring"
}
Response
{
"data": {
"paymentRequests": {
"paymentRequest": PaymentRequestConnectionTypeConnection
}
}
}
plannedDispatches
Type: [UpsideDispatchType]
URL: https://api.octopus.energy/v1/graphql/
All planned device dispatches 24 hours ahead, (usually) in time order.
Query Complexity: 3
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4340: Unable to fetch planned dispatches.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'plannedDispatches' field is deprecated.
Please use 'flexPlannedDispatches' instead.
- Marked as deprecated on 2025-05-27.
- Scheduled for removal on or after 2026-01-16.
You can read more about this deprecation on:
https://announcements.kraken.tech/announcements/public/604/
Arguments
| Name | Description |
|---|---|
|
Query
query PlannedDispatches($accountNumber: String!) {
plannedDispatches(accountNumber: $accountNumber) {
delta
end
meta {
...UpsideDispatchMetaTypeFragment
}
start
}
}
Variables
{
"accountNumber": "A-790DE625"
}
Response
{
"data": {
"plannedDispatches": [
{
"delta": "1.0",
"end": "1987-11-20T19:34:40.092317+00:00",
"meta": UpsideDispatchMetaType,
"start": "2019-01-03T09:40:35.531897+00:00"
}
]
}
}
portfolio
Type: PortfolioType
URL: https://api.octopus.energy/v1/graphql/
Get details about a portfolio, using its portfolio number.
Query Complexity: 2
Possible Errors:
- KT-CT-9403: Received an invalid portfolioId.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query portfolios
Arguments
| Name | Description |
|---|---|
|
Portfolio number to be retrieved. |
Query
query Portfolio($portfolioNumber: String!) {
portfolio(portfolioNumber: $portfolioNumber) {
accounts {
...AccountConnectionTypeConnectionFragment
}
ancestors {
...PortfolioConnectionTypeConnectionFragment
}
billingName
brand
collectiveBilling
createdAt
depth
descendants {
...PortfolioConnectionTypeConnectionFragment
}
id
leadAccountNumber
name
number
operationsTeam {
...OperationsTeamTypeFragment
}
parent {
...PortfolioTypeFragment
}
updatedAt
}
}
Variables
{
"portfolioNumber": "P-026B9E5D"
}
Response
{
"data": {
"portfolio": {
"accounts": AccountConnectionTypeConnection,
"ancestors": PortfolioConnectionTypeConnection,
"billingName": "staff-establish-guy-author-lot",
"brand": "sort-bag-ten-year-customer",
"collectiveBilling": true,
"createdAt": "1996-05-26T05:20:15.019703+00:00",
"depth": 88,
"descendants": PortfolioConnectionTypeConnection,
"id": "19645365",
"leadAccountNumber": "A-CEA10B24",
"name": "behavior-area-sense-third-hotel",
"number": "back-audience-field-hold-thing",
"operationsTeam": OperationsTeamType,
"parent": PortfolioType,
"updatedAt": "1978-03-22T04:23:07.100772+00:00"
}
}
}
portfolioByReference
Type: PortfolioType
URL: https://api.octopus.energy/v1/graphql/
Get details about a portfolio, using its reference.
Query Complexity: 2
Possible Errors:
- KT-CT-9409: Invalid portfolio reference.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query portfolios
Arguments
| Name | Description |
|---|---|
|
Portfolio reference namespace-value pair to filter by. |
Query
query PortfolioByReference($portfolioReference: PortfolioReferenceInput!) {
portfolioByReference(portfolioReference: $portfolioReference) {
accounts {
...AccountConnectionTypeConnectionFragment
}
ancestors {
...PortfolioConnectionTypeConnectionFragment
}
billingName
brand
collectiveBilling
createdAt
depth
descendants {
...PortfolioConnectionTypeConnectionFragment
}
id
leadAccountNumber
name
number
operationsTeam {
...OperationsTeamTypeFragment
}
parent {
...PortfolioTypeFragment
}
updatedAt
}
}
Variables
{
"portfolioReference": PortfolioReferenceInput
}
Response
{
"data": {
"portfolioByReference": {
"accounts": AccountConnectionTypeConnection,
"ancestors": PortfolioConnectionTypeConnection,
"billingName": "standard-amount-spend-dream-case",
"brand": "cut-where-around-option-he",
"collectiveBilling": true,
"createdAt": "1984-02-25T04:10:45.448049+00:00",
"depth": 45,
"descendants": PortfolioConnectionTypeConnection,
"id": "67801851",
"leadAccountNumber": "A-BBBFB9BF",
"name": "maintain-local-director-feeling-decision",
"number": "actually-society-sing-drug-man",
"operationsTeam": OperationsTeamType,
"parent": PortfolioType,
"updatedAt": "2015-09-23T12:38:03.871684+00:00"
}
}
}
possibleErrors
Type: PossibleErrorsOutputType
URL: https://api.octopus.energy/v1/graphql/
Possible errors of the requested query/mutation.
Query Complexity: 1
Possible Errors:
- KT-CT-1606: Query/Mutation not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
(No)
Rate Limits
| Key | Steps |
|---|---|
Ip |
['10/m'] |
Arguments
| Name | Description |
|---|---|
|
Query or Mutation for which to get the possible errors list. |
Query
query PossibleErrors($input: PossibleErrorsInputType!) {
possibleErrors(input: $input) {
authErrors
name
possibleErrors {
...PossibleErrorTypeFragment
}
type
}
}
Variables
{
"input": PossibleErrorsInputType
}
Response
{
"data": {
"possibleErrors": {
"authErrors": true,
"name": "young-school-support-student-because",
"possibleErrors": [PossibleErrorType],
"type": "query"
}
}
}
prepayBalanceSnapshot
Type: PrepayBalanceSnapshotType
URL: https://api.octopus.energy/v1/graphql/
Retrieve a snapshot of a prepay device balance at a moment in time.
Query Complexity: 1
Possible Errors:
- KT-GB-4048: Device not in prepayment mode.
- KT-GB-4049: Balance snapshot not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ESME or GSME's EUI64 ID, e.g. '12-34-5A-FF-FF-6B-C7-89'. |
Query
query PrepayBalanceSnapshot($deviceId: String!) {
prepayBalanceSnapshot(deviceId: $deviceId) {
accumulatedDebtRegisterInMillipence
asAt
creditInPence
debtInPence
emergencyCreditBalanceInMillipence
emergencyCreditInPence
meterBalanceInMillipence
paymentDebtRegisterInMillipence
timeDebtRegisterOneInMillipence
timeDebtRegisterTwoInMillipence
}
}
Variables
{
"deviceId": "45551195"
}
Response
{
"data": {
"prepayBalanceSnapshot": {
"accumulatedDebtRegisterInMillipence": 86,
"asAt": "1994-05-01T04:02:53.313565+00:00",
"creditInPence": 38,
"debtInPence": 91,
"emergencyCreditBalanceInMillipence": 53,
"emergencyCreditInPence": 44,
"meterBalanceInMillipence": 7,
"paymentDebtRegisterInMillipence": 47,
"timeDebtRegisterOneInMillipence": 65,
"timeDebtRegisterTwoInMillipence": 11
}
}
}
prepayPayments
Type: PrepayPaymentConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Payments made to add credit to the account's smart prepay meters.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-GB-4052: Prepayment payments not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
Query
query PrepayPayments(
$accountNumber: String!,
$after: String,
$before: String,
$first: Int,
$last: Int
) {
prepayPayments(
accountNumber: $accountNumber,
after: $after,
before: $before,
first: $first,
last: $last
) {
edgeCount
edges {
...PrepayPaymentConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-A250665D",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10
}
Response
{
"data": {
"prepayPayments": {
"edgeCount": 95,
"edges": [PrepayPaymentConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 7
}
}
}
printBatch
Type: PrintBatchType!
URL: https://api.octopus.energy/v1/graphql/
Get print batch details, including messages in the batch.
Query Complexity: 1
Possible Errors:
- KT-CT-9012: Invalid data.
- KT-CT-9013: Invalid data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query print batches
Query
query PrintBatch($batchId: ID) {
printBatch(batchId: $batchId) {
id
messages {
...PrintMessageTypeConnectionFragment
}
status
}
}
Variables
{
"batchId": "20643808"
}
Response
{
"data": {
"printBatch": {
"id": "81843441",
"messages": PrintMessageTypeConnection,
"status": "OPEN"
}
}
}
productEligibility
Type: ProductEligibilityType
URL: https://api.octopus.energy/v1/graphql/
Define product eligibility.
Query Complexity: 1
Possible Errors:
- KT-CT-4190: Error while defining product eligibility for product enrolment candidate.
- KT-CT-4623: Unauthorized.
- KT-CT-4910: No product exists with the given input.
- KT-GB-4135: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account to which meter point belongs. |
|
Meter point reference/administration number. |
|
Product code for which verify eligibility to. |
Query
query ProductEligibility(
$accountNumber: String!,
$mpxn: String!,
$productCode: String!
) {
productEligibility(
accountNumber: $accountNumber,
mpxn: $mpxn,
productCode: $productCode
) {
ineligibilityReasons {
...ProductIneligibilityReasonDetailsFragment
}
isEligible
}
}
Variables
{
"accountNumber": "A-1FE55DAD",
"mpxn": "would-few-other-protect-character",
"productCode": "make-century-customer-card-democratic"
}
Response
{
"data": {
"productEligibility": {
"ineligibilityReasons": [ProductIneligibilityReasonDetails],
"isEligible": true
}
}
}
productEligibilityV2
Type: ProductEligibilityType
URL: https://api.octopus.energy/v1/graphql/
Define product eligibility using the updated framework.
Query Complexity: 1
Possible Errors:
- KT-CT-4190: Error while defining product eligibility for product enrolment candidate.
- KT-CT-4623: Unauthorized.
- KT-CT-4910: No product exists with the given input.
- KT-GB-4135: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account to which meter point belongs. |
|
Meter point reference/administration number. |
|
Product code for which verify eligibility to. |
Query
query ProductEligibilityV2(
$accountNumber: String!,
$mpxn: String!,
$productCode: String!
) {
productEligibilityV2(
accountNumber: $accountNumber,
mpxn: $mpxn,
productCode: $productCode
) {
ineligibilityReasons {
...ProductIneligibilityReasonDetailsFragment
}
isEligible
}
}
Variables
{
"accountNumber": "A-5137F768",
"mpxn": "look-specific-something-sort-five",
"productCode": "fly-money-imagine-step-both"
}
Response
{
"data": {
"productEligibilityV2": {
"ineligibilityReasons": [ProductIneligibilityReasonDetails],
"isEligible": true
}
}
}
productEnrolment
Type: ProductEnrolmentType
URL: https://api.octopus.energy/v1/graphql/
Get the details of a product enrolment.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can manage product enrolment
Arguments
| Name | Description |
|---|---|
|
The account to which the enrolment belongs. |
|
The ID for the enrolment. |
Query
query ProductEnrolment(
$accountNumber: String!,
$enrolmentId: ID!
) {
productEnrolment(
accountNumber: $accountNumber,
enrolmentId: $enrolmentId
) {
account {
...AccountTypeFragment
}
electricityMeterPoint {
...ElectricityMeterPointTypeFragment
}
gasMeterPoint {
...GasMeterPointTypeFragment
}
id
product {
...EnergyProductTypeFragment
}
stages {
...ProductEnrolmentStageTypeFragment
}
status
}
}
Variables
{
"accountNumber": "A-CB38CBC1",
"enrolmentId": "98925058"
}
Response
{
"data": {
"productEnrolment": {
"account": AccountType,
"electricityMeterPoint": ElectricityMeterPointType,
"gasMeterPoint": GasMeterPointType,
"id": "36709568",
"product": EnergyProductType,
"stages": [ProductEnrolmentStageType],
"status": "NOT_STARTED"
}
}
}
productEnrolments
Type: [ProductEnrolmentType]
URL: https://api.octopus.energy/v1/graphql/
Get all of the enrolments for an account.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can manage product enrolment
Arguments
| Name | Description |
|---|---|
|
The account to find all the enrolments for. |
Query
query ProductEnrolments($accountNumber: String!) {
productEnrolments(accountNumber: $accountNumber) {
account {
...AccountTypeFragment
}
electricityMeterPoint {
...ElectricityMeterPointTypeFragment
}
gasMeterPoint {
...GasMeterPointTypeFragment
}
id
product {
...EnergyProductTypeFragment
}
stages {
...ProductEnrolmentStageTypeFragment
}
status
}
}
Variables
{
"accountNumber": "A-DC61C54C"
}
Response
{
"data": {
"productEnrolments": [
{
"account": AccountType,
"electricityMeterPoint": ElectricityMeterPointType,
"gasMeterPoint": GasMeterPointType,
"id": "43642936",
"product": EnergyProductType,
"stages": [ProductEnrolmentStageType],
"status": "NOT_STARTED"
}
]
}
}
properties
Type: [PropertyType]
URL: https://api.octopus.energy/v1/graphql/
The properties attached to the given account.
This field requires the Authorization header to be set.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can book smart meter appointments
OR Can display siteworks appointments
OR Can query property
OR Can query property meters
OR Can submit meter readings
Query
query Properties(
$accountNumber: String!,
$active: Boolean
) {
properties(
accountNumber: $accountNumber,
active: $active
) {
address
ancestors {
...PropertyConnectionFragment
}
availableSmets2InstallationTimeslots {
...Smets2InstallationTimeslotTypeFragment
}
coordinates {
...CoordinatesTypeFragment
}
descendants {
...PropertyConnectionFragment
}
electricityMeterPoints {
...ElectricityMeterPointTypeFragment
}
embeddedNetwork {
...EmbeddedNetworkTypeFragment
}
gasMeterPoints {
...GasMeterPointTypeFragment
}
id
isChangeOfTenancyOngoing
isSmets2InstallationAllowed
label
measurements {
...MeasurementConnectionFragment
}
occupancyPeriods {
...OccupancyPeriodTypeFragment
}
parent {
...PropertyInterfaceFragment
}
postcode
richAddress {
...PropertyRichAddressTypeFragment
}
smartDeviceNetworks {
...SmartMeterDeviceNetworkTypeFragment
}
splitAddress
wanCoverage
}
}
Variables
{
"accountNumber": "A-4B3F9AF4",
"active": true
}
Response
{
"data": {
"properties": [
{
"address": "above-choose-expect-market-pass",
"ancestors": PropertyConnection,
"availableSmets2InstallationTimeslots": [Smets2InstallationTimeslotType],
"coordinates": CoordinatesType,
"descendants": PropertyConnection,
"electricityMeterPoints": [ElectricityMeterPointType],
"embeddedNetwork": EmbeddedNetworkType,
"gasMeterPoints": [GasMeterPointType],
"id": "86780624",
"isChangeOfTenancyOngoing": true,
"isSmets2InstallationAllowed": true,
"label": "choice-receive-success-agreement-common",
"measurements": MeasurementConnection,
"occupancyPeriods": [OccupancyPeriodType],
"parent": PropertyInterface,
"postcode": "human-store-good-prepare-difficult",
"richAddress": PropertyRichAddressType,
"smartDeviceNetworks": [SmartMeterDeviceNetworkType],
"splitAddress": "best-address-within-air-let",
"wanCoverage": "HIGH"
}
]
}
}
propertiesSearch
Type: [PropertySearchResult!]!
URL: https://api.octopus.energy/v1/graphql/
Search for properties that are already in Kraken and match the search term.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query property
Arguments
| Name | Description |
|---|---|
|
The search term. It can be an address or a meter point identifier. |
Query
query PropertiesSearch($searchTerm: String!) {
propertiesSearch(searchTerm: $searchTerm) {
property {
...PropertyTypeFragment
}
score
}
}
Variables
{
"searchTerm": "southern-better-under-region-career"
}
Response
{
"data": {
"propertiesSearch": [
{
"property": PropertyType,
"score": "1.0"
}
]
}
}
property
Type: PropertyType
URL: https://api.octopus.energy/v1/graphql/
A property with the given ID. Usually associated with supply points.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ID of the property. |
Query
query Property($id: ID!) {
property(id: $id) {
address
ancestors {
...PropertyConnectionFragment
}
availableSmets2InstallationTimeslots {
...Smets2InstallationTimeslotTypeFragment
}
coordinates {
...CoordinatesTypeFragment
}
descendants {
...PropertyConnectionFragment
}
electricityMeterPoints {
...ElectricityMeterPointTypeFragment
}
embeddedNetwork {
...EmbeddedNetworkTypeFragment
}
gasMeterPoints {
...GasMeterPointTypeFragment
}
id
isChangeOfTenancyOngoing
isSmets2InstallationAllowed
label
measurements {
...MeasurementConnectionFragment
}
occupancyPeriods {
...OccupancyPeriodTypeFragment
}
parent {
...PropertyInterfaceFragment
}
postcode
richAddress {
...PropertyRichAddressTypeFragment
}
smartDeviceNetworks {
...SmartMeterDeviceNetworkTypeFragment
}
splitAddress
wanCoverage
}
}
Variables
{
"id": "98234386"
}
Response
{
"data": {
"property": {
"address": "type-if-station-because-each",
"ancestors": PropertyConnection,
"availableSmets2InstallationTimeslots": [Smets2InstallationTimeslotType],
"coordinates": CoordinatesType,
"descendants": PropertyConnection,
"electricityMeterPoints": [ElectricityMeterPointType],
"embeddedNetwork": EmbeddedNetworkType,
"gasMeterPoints": [GasMeterPointType],
"id": "24889557",
"isChangeOfTenancyOngoing": true,
"isSmets2InstallationAllowed": true,
"label": "exactly-benefit-spend-daughter-mean",
"measurements": MeasurementConnection,
"occupancyPeriods": [OccupancyPeriodType],
"parent": PropertyInterface,
"postcode": "factor-system-receive-institution-music",
"richAddress": PropertyRichAddressType,
"smartDeviceNetworks": [SmartMeterDeviceNetworkType],
"splitAddress": "able-management-show-pick-difficult",
"wanCoverage": "HIGH"
}
}
}
propertySearch
Type: [PropertyType]
URL: https://api.octopus.energy/v1/graphql/
Search for properties that are already in Kraken and match the search term.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query property
Deprecated
The 'propertySearch' field is deprecated.
This query is being deprecated in favour of `propertiesSearch`. The latter returns not only the matched properties but the level of confidence in the results through the `score` field.
- Marked as deprecated on 2023-05-23.
- Scheduled for removal on or after 2024-01-01.
Arguments
| Name | Description |
|---|---|
|
The search term. It can be an address or a meter point identifier. |
Query
query PropertySearch($searchTerm: String!) {
propertySearch(searchTerm: $searchTerm) {
address
ancestors {
...PropertyConnectionFragment
}
availableSmets2InstallationTimeslots {
...Smets2InstallationTimeslotTypeFragment
}
coordinates {
...CoordinatesTypeFragment
}
descendants {
...PropertyConnectionFragment
}
electricityMeterPoints {
...ElectricityMeterPointTypeFragment
}
embeddedNetwork {
...EmbeddedNetworkTypeFragment
}
gasMeterPoints {
...GasMeterPointTypeFragment
}
id
isChangeOfTenancyOngoing
isSmets2InstallationAllowed
label
measurements {
...MeasurementConnectionFragment
}
occupancyPeriods {
...OccupancyPeriodTypeFragment
}
parent {
...PropertyInterfaceFragment
}
postcode
richAddress {
...PropertyRichAddressTypeFragment
}
smartDeviceNetworks {
...SmartMeterDeviceNetworkTypeFragment
}
splitAddress
wanCoverage
}
}
Variables
{
"searchTerm": "international-point-scene-large-develop"
}
Response
{
"data": {
"propertySearch": [
{
"address": "radio-responsibility-security-health-bed",
"ancestors": PropertyConnection,
"availableSmets2InstallationTimeslots": [Smets2InstallationTimeslotType],
"coordinates": CoordinatesType,
"descendants": PropertyConnection,
"electricityMeterPoints": [ElectricityMeterPointType],
"embeddedNetwork": EmbeddedNetworkType,
"gasMeterPoints": [GasMeterPointType],
"id": "18970972",
"isChangeOfTenancyOngoing": true,
"isSmets2InstallationAllowed": true,
"label": "old-election-yes-attack-inside",
"measurements": MeasurementConnection,
"occupancyPeriods": [OccupancyPeriodType],
"parent": PropertyInterface,
"postcode": "good-sort-develop-kitchen-technology",
"richAddress": PropertyRichAddressType,
"smartDeviceNetworks": [SmartMeterDeviceNetworkType],
"splitAddress": "agent-spend-sing-second-evidence",
"wanCoverage": "HIGH"
}
]
}
}
providerVirtualKeyDetails
Type: ProviderVirtualKeyDetailsType
URL: https://api.octopus.energy/v1/graphql/
Virtual key details (e.g. certificate public key) for the provider (if available).
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The device type to get the virtual key details for (as providers may support multiple). |
|
The provider to get the virtual key details for. |
Query
query ProviderVirtualKeyDetails(
$deviceType: KrakenFlexDeviceTypes!,
$provider: ProviderChoices!
) {
providerVirtualKeyDetails(
deviceType: $deviceType,
provider: $provider
) {
virtualKeyName
virtualKeyUri
}
}
Variables
{
"deviceType": "BATTERIES",
"provider": "BYD"
}
Response
{
"data": {
"providerVirtualKeyDetails": {
"virtualKeyName": "long-policy-maybe-budget-his",
"virtualKeyUri": "parent-leader-today-although-others"
}
}
}
queryComplexity
Type: QueryComplexityOutputType
URL: https://api.octopus.energy/v1/graphql/
Get the complexity of a query.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access third party queries
Arguments
| Name | Description |
|---|---|
|
Query and relevant variables required to calculate the complexity. |
Query
query QueryComplexity($input: QueryComplexityInputType!) {
queryComplexity(input: $input) {
complexityValue
}
}
Variables
{
"input": QueryComplexityInputType
}
Response
{
"data": {
"queryComplexity": {
"complexityValue": 59
}
}
}
question
Type: String
URL: https://api.octopus.energy/v1/graphql/
Get the customer feedback survey question.
Query Complexity: 1
Possible Errors:
- KT-CT-5513: Invalid data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can submit customer feedback
Arguments
| Name | Description |
|---|---|
|
Query
query Question($formId: Int!) {
question(formId: $formId)
}
Variables
{
"formId": 84712020
}
Response
{
"data": {
"question": "who-guy-clearly-pay-still"
}
}
quote
Type: QuoteType
URL: https://api.octopus.energy/v1/graphql/
This returns the quote with the given code.
If the code was not provided, this query used to return an empty quote, but this usage is no longer supported, as the dedicated consumptionEstimates query serves that purpose.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Unique identifying code of the quote to retrieve. This argument is optional, but leaving it empty is not supported anymore. |
Query
query Quote($code: String) {
quote(code: $code) {
address {
...QuoteAddressTypeFragment
}
code
elecAnnualConsumptionDay
elecAnnualConsumptionNight
elecAnnualConsumptionStandard
elecEstimate
gasAnnualConsumption
gasEstimate
gspGroupId
includesElectricity
includesGas
isBusiness
latitude
longitude
meterType
mpan
mprn
partnerProductId
paymentMethod
postcode
quotedProducts {
...QuotedProductTypeFragment
}
termsAndConditions {
...TermsAndConditionsTypeFragment
}
}
}
Variables
{
"code": "option-able-rest-black-lot"
}
Response
{
"data": {
"quote": {
"address": QuoteAddressType,
"code": "ask-personal-lawyer-already-case",
"elecAnnualConsumptionDay": 64,
"elecAnnualConsumptionNight": 84,
"elecAnnualConsumptionStandard": 60,
"elecEstimate": true,
"gasAnnualConsumption": 10,
"gasEstimate": true,
"gspGroupId": "57785593",
"includesElectricity": true,
"includesGas": true,
"isBusiness": true,
"latitude": 315.54,
"longitude": 740.73,
"meterType": "NO_METER",
"mpan": "skin-realize-establish-citizen-with",
"mprn": "wall-central-training-nor-compare",
"partnerProductId": 1,
"paymentMethod": "DIRECTDEBIT",
"postcode": "spring-church-hold-Mrs-rise",
"quotedProducts": [QuotedProductType],
"termsAndConditions": TermsAndConditionsType
}
}
}
quoteConfigurationByNumber
Type: QuoteConfigurationType
URL: https://api.octopus.energy/v1/graphql/
Get a quote configuration by its number.
Query Complexity: 2
Possible Errors:
- KT-CT-14701: QuoteConfiguration not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query quote configuration
Arguments
| Name | Description |
|---|---|
|
Unique number identifying the quote configuration. |
Query
query QuoteConfigurationByNumber($number: String) {
quoteConfigurationByNumber(number: $number) {
contractEnd
contractStart
createdBy
expiresAt
extraDetailsItems {
...QuoteConfigurationExtraDetailItemTypeFragment
}
extraQuotingParams {
...ExtraQuotingParamsTypeFragment
}
number
opportunityNumber
status
terms {
...QuoteTermInterfaceFragment
}
}
}
Variables
{
"number": "green-outside-allow-outside-everything"
}
Response
{
"data": {
"quoteConfigurationByNumber": {
"contractEnd": "1984-05-03T06:41:57.283223+00:00",
"contractStart": "1980-04-14T12:27:58.143362+00:00",
"createdBy": "politics-head-western-serve-as",
"expiresAt": "2019-10-28T08:16:28.667305+00:00",
"extraDetailsItems": [QuoteConfigurationExtraDetailItemType],
"extraQuotingParams": ExtraQuotingParamsType,
"number": "technology-experience-along-interview-hospital",
"opportunityNumber": "south-fly-responsibility-pressure-fine",
"status": "DRAFT",
"terms": QuoteTermInterface
}
}
}
quoteRequest
Type: QuoteRequest
URL: https://api.octopus.energy/v1/graphql/
Retrieve a quote request by its code.
Query Complexity: 1
Possible Errors:
- KT-GB-4618: Quote request not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Code of the quote request. |
Query
query QuoteRequest($quoteCode: String!) {
quoteRequest(quoteCode: $quoteCode) {
code
createdAt
electricitySupplyPoints {
...ElectricitySupplyPointFragment
}
gasSupplyPoints {
...GasSupplyPointFragment
}
termsAndConditions {
...TermsAndConditionsFragment
}
}
}
Variables
{
"quoteCode": "north-truth-environment-others-year"
}
Response
{
"data": {
"quoteRequest": {
"code": "could-light-nothing-score-what",
"createdAt": "1970-12-08T04:23:43.459727+00:00",
"electricitySupplyPoints": [ElectricitySupplyPoint],
"gasSupplyPoints": [GasSupplyPoint],
"termsAndConditions": [TermsAndConditions]
}
}
}
quotingParamDefinitionsForProductOffering
Type: QuotedOfferingParamsType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-12403: Product offering not found.
- KT-CT-12404: Product offering has expired.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can create quoting offer group
Arguments
| Name | Description |
|---|---|
|
The identifier of the product offering. |
Query
query QuotingParamDefinitionsForProductOffering($productOfferingIdentifier: ID) {
quotingParamDefinitionsForProductOffering(productOfferingIdentifier: $productOfferingIdentifier) {
offeringComponents {
...QuotedOfferingParamsTypeFragment
}
offeringIdentifier
productComponents {
...QuotedProductComponentTypeFragment
}
}
}
Variables
{
"productOfferingIdentifier": "81483761"
}
Response
{
"data": {
"quotingParamDefinitionsForProductOffering": {
"offeringComponents": [QuotedOfferingParamsType],
"offeringIdentifier": "32100635",
"productComponents": [QuotedProductComponentType]
}
}
}
rateGroupTouScheme
Type: TimeOfUseSchemeType
URL: https://api.octopus.energy/v1/graphql/
Get the time of use scheme definition and available time slots for a rate group within a product specification.
Query Complexity: 1
Possible Errors:
- KT-CT-12010: Unable to find the product's specification.
- KT-CT-12049: Rate specification not found in the given product specification.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query catalog offerings
Arguments
| Name | Description |
|---|---|
|
The rate group code (rate specification code). |
|
The identifier of the product specification. |
Query
query RateGroupTouScheme(
$rateGroupCode: String!,
$specificationIdentifier: String!
) {
rateGroupTouScheme(
rateGroupCode: $rateGroupCode,
specificationIdentifier: $specificationIdentifier
) {
name
timeslots {
...TimeSlotWithActivationRuleTypeFragment
}
timezone
}
}
Variables
{
"rateGroupCode": "notice-degree-number-significant-full",
"specificationIdentifier": "46127177"
}
Response
{
"data": {
"rateGroupTouScheme": {
"name": "form-hospital-western-because-tough",
"timeslots": [TimeSlotWithActivationRuleType],
"timezone": "indeed-situation-stay-beat-probably"
}
}
}
rateLimitInfo
Type: CombinedRateLimitInformation
URL: https://api.octopus.energy/v1/graphql/
Combined information about points-allowance rate limiting and request-specific rate limiting.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['10/m'] |
Query
query RateLimitInfo {
rateLimitInfo {
fieldSpecificRateLimits {
...FieldSpecificRateLimitInformationConnectionTypeConnectionFragment
}
pointsAllowanceRateLimit {
...PointsAllowanceRateLimitInformationFragment
}
}
}
Response
{
"data": {
"rateLimitInfo": {
"fieldSpecificRateLimits": FieldSpecificRateLimitInformationConnectionTypeConnection,
"pointsAllowanceRateLimit": PointsAllowanceRateLimitInformation
}
}
}
readingConsentGranularity
Type: ReadingConsentGranularityType
URL: https://api.octopus.energy/v1/graphql/
Get the current reading consent granularity for a meter point.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query meter point
Arguments
| Name | Description |
|---|---|
|
The MPAN of the meter point. |
Query
query ReadingConsentGranularity($mpan: String!) {
readingConsentGranularity(mpan: $mpan) {
granularityValue
}
}
Variables
{
"mpan": "fish-out-skin-item-think"
}
Response
{
"data": {
"readingConsentGranularity": {
"granularityValue": "simply-shoulder-why-manage-as"
}
}
}
registeredKrakenflexDevice
Type: KrakenFlexDeviceType
URL: https://api.octopus.energy/v1/graphql/
A device registered with KrakenFlex for a given account.
Query Complexity: 2
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'registeredKrakenflexDevice' field is deprecated.
Please use 'devices' instead.
- Marked as deprecated on 2024-04-23.
- Scheduled for removal on or after 2026-03-01.
You can read more about this deprecation on:
https://announcements.kraken.tech/announcements/public/677/
Arguments
| Name | Description |
|---|---|
|
Query
query RegisteredKrakenflexDevice($accountNumber: String!) {
registeredKrakenflexDevice(accountNumber: $accountNumber) {
chargePointMake
chargePointModel
chargePointPowerInKw
createdAt
hasToken
krakenflexDeviceId
provider
stateOfChargeLimit {
...StateOfChargeLimitFragment
}
status
suspended
testDispatchFailureReason
vehicleBatterySizeInKwh
vehicleMake
vehicleModel
}
}
Variables
{
"accountNumber": "A-67090CCF"
}
Response
{
"data": {
"registeredKrakenflexDevice": {
"chargePointMake": "down-better-again-note-far",
"chargePointModel": "professor-from-shake-spend-training",
"chargePointPowerInKw": "1.0",
"createdAt": "1978-04-08T13:59:00.773645+00:00",
"hasToken": true,
"krakenflexDeviceId": "77226349",
"provider": "BYD",
"stateOfChargeLimit": StateOfChargeLimit,
"status": "generation-lot-budget-floor-between",
"suspended": true,
"testDispatchFailureReason": "NONE",
"vehicleBatterySizeInKwh": "1.0",
"vehicleMake": "however-range-defense-bag-agree",
"vehicleModel": "street-capital-opportunity-enough-nor"
}
}
}
returnSchedule
Type: [DepositReturnScheduleOutput]
URL: https://api.octopus.energy/v1/graphql/
Get deposit agreement related return schedules for a given account.
Query Complexity: 1
Possible Errors:
- KT-CT-4177: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can use deposit system
Arguments
| Name | Description |
|---|---|
|
Query
query ReturnSchedule($accountNumber: String!) {
returnSchedule(accountNumber: $accountNumber) {
amount
dueDate
status
}
}
Variables
{
"accountNumber": "A-C9A9924D"
}
Response
{
"data": {
"returnSchedule": [
{
"amount": 28,
"dueDate": "1979-01-19",
"status": "test-onto-race-must-recognize"
}
]
}
}
routingAttributes
Type: [RoutingAttributeType]!
URL: https://api.octopus.energy/v1/graphql/
Get routing attributes available for call routing configuration.
Query Complexity: 2
Possible Errors:
- KT-CT-11816: Invalid routing attribute category.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query calls
Arguments
| Name | Description |
|---|---|
|
Filter by category (LANGUAGE, OPERATIONS_GROUP, SKILL). |
|
Filter by friendly name (case-insensitive). |
Query
query RoutingAttributes(
$category: String,
$search: String
) {
routingAttributes(
category: $category,
search: $search
) {
category
friendlyName
isActive
ref
subcategory
}
}
Variables
{
"category": "those-happy-ok-lead-able",
"search": "us-be-road-some-play"
}
Response
{
"data": {
"routingAttributes": [
{
"category": "test-result-create-feel-role",
"friendlyName": "similar-late-manager-station-page",
"isActive": true,
"ref": "live-compare-point-find-customer",
"subcategory": "poor-project-pick-help-general"
}
]
}
}
salesFunnelByCode
Type: SalesFunnel
URL: https://api.octopus.energy/v1/graphql/
Get the sales funnel by input.
Query Complexity: 1
Possible Errors:
- KT-CT-8912: Funnel not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query sales funnels
Arguments
| Name | Description |
|---|---|
|
Input fields for retrieving the sales funnel. |
Query
query SalesFunnelByCode($input: SalesFunnelInput!) {
salesFunnelByCode(input: $input) {
code
collections {
...CollectionFragment
}
funnelType
name
rules {
...SalesFunnelRuleFragment
}
stages {
...SalesFunnelStageFragment
}
status
}
}
Variables
{
"input": SalesFunnelInput
}
Response
{
"data": {
"salesFunnelByCode": {
"code": "would-food-mention-east-mission",
"collections": [Collection],
"funnelType": "LEAD",
"name": "open-such-meeting-dog-ok",
"rules": [SalesFunnelRule],
"stages": [SalesFunnelStage],
"status": "DRAFT"
}
}
}
salesFunnels
Type: [SalesFunnel]
URL: https://api.octopus.energy/v1/graphql/
Get all sales funnels.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query sales funnels
Arguments
| Name | Description |
|---|---|
|
Input fields for retrieving the sales funnels. |
Query
query SalesFunnels($input: SalesFunnelsInput) {
salesFunnels(input: $input) {
code
collections {
...CollectionFragment
}
funnelType
name
rules {
...SalesFunnelRuleFragment
}
stages {
...SalesFunnelStageFragment
}
status
}
}
Variables
{
"input": SalesFunnelsInput
}
Response
{
"data": {
"salesFunnels": [
{
"code": "their-clearly-clear-low-theory",
"collections": [Collection],
"funnelType": "LEAD",
"name": "region-open-son-challenge-down",
"rules": [SalesFunnelRule],
"stages": [SalesFunnelStage],
"status": "DRAFT"
}
]
}
}
searchLead
Type: LeadIdType
URL: https://api.octopus.energy/v1/graphql/
Search and return the identifiers of a lead.
Query Complexity: 2
Possible Errors:
- KT-CT-8920: Search filters are invalid.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query leads
Arguments
| Name | Description |
|---|---|
|
Filters to search for leads. All passed filters will be checked against the lead. |
Query
query SearchLead($filters: SearchLeadFilters!) {
searchLead(filters: $filters) {
number
}
}
Variables
{
"filters": SearchLeadFilters
}
Response
{
"data": {
"searchLead": {
"number": "consumer-two-might-point-teach"
}
}
}
segInstallation
Type: SEGInstallationType!
URL: https://api.octopus.energy/v1/graphql/
The validity of a SEG installation via the MCS installation database.
Query Complexity: 5
Possible Errors:
- KT-GB-4505: The provided MCS certificate number is not valid.
- KT-GB-4506: No data returned from the MCS API.
- KT-GB-4507: The MCS API has returned an invalid response, please try again later.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The MCS certificate number. |
Query
query SegInstallation($mcsCertificateNumber: String!) {
segInstallation(mcsCertificateNumber: $mcsCertificateNumber) {
isValid
}
}
Variables
{
"mcsCertificateNumber": "base-sport-write-eat-take"
}
Response
{
"data": {
"segInstallation": {
"isValid": true
}
}
}
settableConsentGranularities
Type: [ConsentGranularityValue]
URL: https://api.octopus.energy/v1/graphql/
Get valid consent granularities for a meter point, a product or both.
Query Complexity: 2
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-GB-4502: Unable to determine acceptable granularities. Please try again shortly.
- KT-GB-4504: At least one parameter must be provided.
- KT-GB-9514: No available product found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query meter point
Arguments
| Name | Description |
|---|---|
|
The MPAN of the meter point. |
|
The product code. |
Query
query SettableConsentGranularities(
$mpan: String,
$productCode: ID
) {
settableConsentGranularities(
mpan: $mpan,
productCode: $productCode
)
}
Variables
{
"mpan": "support-character-early-report-vote",
"productCode": "16939951"
}
Response
{
"data": {
"settableConsentGranularities": "HALF_HOURLY"
}
}
shoptopusVoucherAvailability
Type: [ShoptopusVoucherAvailabilityType]
URL: https://api.octopus.energy/v1/graphql/
Describes availability of Shoptopus Vouchers for given Octopoint amounts.
Query Complexity: 1
Possible Errors:
- KT-GB-9319: This feature is not currently available.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'shoptopusVoucherAvailability' field is deprecated.
The Octoplus feature is going through changes. This query is no longer available.
- Marked as deprecated on 2026-02-10.
- Scheduled for removal on or after 2026-08-10.
Arguments
| Name | Description |
|---|---|
|
The values (in Octopoints) for which to return voucher availability (maximum 5 values). |
Query
query ShoptopusVoucherAvailability($voucherValues: [Int]!) {
shoptopusVoucherAvailability(voucherValues: $voucherValues) {
availability
value
}
}
Variables
{
"voucherValues": 94
}
Response
{
"data": {
"shoptopusVoucherAvailability": [
{
"availability": true,
"value": 34
}
]
}
}
siteworksAppointmentSlots
Type: SiteworksAppointmentSlotsType
URL: https://api.octopus.energy/v1/graphql/
Returns set of available siteworks appointment slots for the given property.
Query Complexity: 1
Possible Errors:
- KT-GB-4214: Booking is not supported with the agent appointed at property.
- KT-GB-4217: Unknown agent carrying out the appointment.
- KT-GB-4221: Could not confirm duplicate property.
- KT-GB-4227: No account for property.
- KT-GB-4232: No meterpoint was found or provided in the payload.
- KT-GB-4239: Job type value is not supported by the agent appointed at property.
- KT-GB-4240: Job type entry is not enabled.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The booking agent appointment reference number. |
|
|
|
The date to search for appointments from. |
|
If job type is not specified, the default job type for the booking adapter will be used. |
|
The property ID to search for. |
|
The duration of the appointment to search for. |
Query
query SiteworksAppointmentSlots(
$agentReference: String,
$calculationId: String,
$fromDate: Date,
$jobType: String,
$propertyId: ID!,
$slotDuration: SlotDuration
) {
siteworksAppointmentSlots(
agentReference: $agentReference,
calculationId: $calculationId,
fromDate: $fromDate,
jobType: $jobType,
propertyId: $propertyId,
slotDuration: $slotDuration
) {
calculationId
expectedJobDurationMinutes
fetchStatus
slots {
...SiteworksAppointmentSlotTypeFragment
}
}
}
Variables
{
"agentReference": "let-on-drop-impact-brother",
"calculationId": "99322777",
"fromDate": "2013-04-24",
"jobType": "exactly-actually-professor-number-land",
"propertyId": "65988099",
"slotDuration": "TWO_HOUR"
}
Response
{
"data": {
"siteworksAppointmentSlots": {
"calculationId": "56924300",
"expectedJobDurationMinutes": 67,
"fetchStatus": "PENDING",
"slots": [SiteworksAppointmentSlotType]
}
}
}
siteworksBookingAccountSearchByMpan
Type: SiteworksBookingAccountType
URL: https://api.octopus.energy/v1/graphql/
Get siteworks booking information for an account given an MPAN.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'siteworksBookingAccountSearchByMpan' field is deprecated.
Please use accountsSearch instead.
- Marked as deprecated on 2026-03-01.
- Scheduled for removal on or after 2026-06-01.
Arguments
| Name | Description |
|---|---|
|
The MPAN to search for. |
Query
query SiteworksBookingAccountSearchByMpan($mpan: String!) {
siteworksBookingAccountSearchByMpan(mpan: $mpan) {
accountType
activeCampaigns {
...SiteworksCampaignTypeFragment
}
billingName
brand
canModifyPayments {
...CanModifyPaymentsTypeFragment
}
marketSupplyAgreements {
...AgreementConnectionFragment
}
number
properties {
...SiteworksBookingPropertyTypeFragment
}
siteworksRequests {
...SiteworksRequestTypeFragment
}
smets2Interest
status
users {
...AccountUserTypeFragment
}
}
}
Variables
{
"mpan": "arm-husband-month-office-like"
}
Response
{
"data": {
"siteworksBookingAccountSearchByMpan": {
"accountType": "city-campaign-newspaper-senior-couple",
"activeCampaigns": [SiteworksCampaignType],
"billingName": "view-media-order-recently-person",
"brand": "ground-education-defense-prove-eye",
"canModifyPayments": CanModifyPaymentsType,
"marketSupplyAgreements": AgreementConnection,
"number": "attention-series-imagine-power-adult",
"properties": [SiteworksBookingPropertyType],
"siteworksRequests": [SiteworksRequestType],
"smets2Interest": "PRIORITY",
"status": "PENDING",
"users": [AccountUserType]
}
}
}
siteworksBookingAccountSearchByMprn
Type: SiteworksBookingAccountType
URL: https://api.octopus.energy/v1/graphql/
Get siteworks booking information for an account given an MPRN.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'siteworksBookingAccountSearchByMprn' field is deprecated.
Please use accountsSearch instead.
- Marked as deprecated on 2026-03-01.
- Scheduled for removal on or after 2026-06-01.
Arguments
| Name | Description |
|---|---|
|
The MPRN to search for. |
Query
query SiteworksBookingAccountSearchByMprn($mprn: String!) {
siteworksBookingAccountSearchByMprn(mprn: $mprn) {
accountType
activeCampaigns {
...SiteworksCampaignTypeFragment
}
billingName
brand
canModifyPayments {
...CanModifyPaymentsTypeFragment
}
marketSupplyAgreements {
...AgreementConnectionFragment
}
number
properties {
...SiteworksBookingPropertyTypeFragment
}
siteworksRequests {
...SiteworksRequestTypeFragment
}
smets2Interest
status
users {
...AccountUserTypeFragment
}
}
}
Variables
{
"mprn": "four-create-often-might-executive"
}
Response
{
"data": {
"siteworksBookingAccountSearchByMprn": {
"accountType": "north-both-upon-finish-late",
"activeCampaigns": [SiteworksCampaignType],
"billingName": "huge-expect-study-radio-majority",
"brand": "official-technology-cold-event-front",
"canModifyPayments": CanModifyPaymentsType,
"marketSupplyAgreements": AgreementConnection,
"number": "cell-group-program-image-provide",
"properties": [SiteworksBookingPropertyType],
"siteworksRequests": [SiteworksRequestType],
"smets2Interest": "PRIORITY",
"status": "PENDING",
"users": [AccountUserType]
}
}
}
siteworksBookingAccountSearchByNumber
Type: SiteworksBookingAccountType
URL: https://api.octopus.energy/v1/graphql/
Get siteworks booking information for an account given its number.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'siteworksBookingAccountSearchByNumber' field is deprecated.
Please use accountsSearch instead.
- Marked as deprecated on 2026-03-01.
- Scheduled for removal on or after 2026-06-01.
Arguments
| Name | Description |
|---|---|
|
The account number to search for. |
Query
query SiteworksBookingAccountSearchByNumber($accountNumber: String!) {
siteworksBookingAccountSearchByNumber(accountNumber: $accountNumber) {
accountType
activeCampaigns {
...SiteworksCampaignTypeFragment
}
billingName
brand
canModifyPayments {
...CanModifyPaymentsTypeFragment
}
marketSupplyAgreements {
...AgreementConnectionFragment
}
number
properties {
...SiteworksBookingPropertyTypeFragment
}
siteworksRequests {
...SiteworksRequestTypeFragment
}
smets2Interest
status
users {
...AccountUserTypeFragment
}
}
}
Variables
{
"accountNumber": "A-B6AF02E4"
}
Response
{
"data": {
"siteworksBookingAccountSearchByNumber": {
"accountType": "range-ready-everybody-push-specific",
"activeCampaigns": [SiteworksCampaignType],
"billingName": "mouth-cover-now-ok-give",
"brand": "bank-recently-behind-either-all",
"canModifyPayments": CanModifyPaymentsType,
"marketSupplyAgreements": AgreementConnection,
"number": "down-site-myself-require-notice",
"properties": [SiteworksBookingPropertyType],
"siteworksRequests": [SiteworksRequestType],
"smets2Interest": "PRIORITY",
"status": "PENDING",
"users": [AccountUserType]
}
}
}
siteworksBookingAccountSearchByPostcode
Type: SiteworksBookingAccountConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get siteworks booking information for accounts at a given postcode.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'siteworksBookingAccountSearchByPostcode' field is deprecated.
Please use accountsSearch instead.
- Marked as deprecated on 2026-03-01.
- Scheduled for removal on or after 2026-06-01.
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
|
|
|
|
The postcode to search for. |
|
Filter the accounts by status. |
Query
query SiteworksBookingAccountSearchByPostcode(
$after: String,
$before: String,
$first: Int,
$last: Int,
$postcode: String!,
$statuses: [AccountStatusChoices]
) {
siteworksBookingAccountSearchByPostcode(
after: $after,
before: $before,
first: $first,
last: $last,
postcode: $postcode,
statuses: $statuses
) {
edgeCount
edges {
...SiteworksBookingAccountConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"postcode": "particularly-until-do-toward-note",
"statuses": "PENDING"
}
Response
{
"data": {
"siteworksBookingAccountSearchByPostcode": {
"edgeCount": 45,
"edges": [SiteworksBookingAccountConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 49
}
}
}
siteworksGetRtsPrimarySecondaryMpans
Type: [RTSPrimarySecondaryMPANs]!
URL: https://api.octopus.energy/v1/graphql/
Calculate the primary and secondary MPANs for an RTS property.
Query Complexity: 1
Possible Errors:
- KT-GB-4235: The property is not an RTS property.
- KT-GB-4236: Unable to determine the primary and secondary MPANs for property.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can create siteworks appointments
Deprecated
The 'siteworksGetRtsPrimarySecondaryMpans' field is deprecated.
Only for use during the RTS transition.
- Marked as deprecated on 2025-08-01.
- Scheduled for removal on or after 2025-09-01.
Arguments
| Name | Description |
|---|---|
|
The id of the property. |
Query
query SiteworksGetRtsPrimarySecondaryMpans($propertyId: Int!) {
siteworksGetRtsPrimarySecondaryMpans(propertyId: $propertyId) {
mpan
type
}
}
Variables
{
"propertyId": 24627617
}
Response
{
"data": {
"siteworksGetRtsPrimarySecondaryMpans": [
{
"mpan": "past-floor-me-south-card",
"type": "quality-attention-environment-perform-serious"
}
]
}
}
siteworksRequests
Type: CoreSiteworksRequestConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
A query to get a subset of Requests.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Deprecated
The 'siteworksRequests' field is deprecated.
Please use getOnSiteJobsRequests instead.
- Marked as deprecated on 2026-03-01.
- Scheduled for removal on or after 2026-09-01.
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Only requests created after this datetime will be included. |
|
|
|
A list of request IDs. If provided, only these requests will be returned. |
|
|
|
Only requests with a status in this list will be included. |
Query
query SiteworksRequests(
$after: String,
$before: String,
$createdAfter: DateTime,
$first: Int,
$ids: [UUID],
$last: Int,
$statuses: [RequestStatus]
) {
siteworksRequests(
after: $after,
before: $before,
createdAfter: $createdAfter,
first: $first,
ids: $ids,
last: $last,
statuses: $statuses
) {
edgeCount
edges {
...CoreSiteworksRequestConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"createdAfter": "1998-05-03T19:10:03.975296+00:00",
"first": 10,
"ids": "466c8476-4c51-4ce0-a8d5-b24784008af4",
"last": 10,
"statuses": "APPROVAL_PENDING"
}
Response
{
"data": {
"siteworksRequests": {
"edgeCount": 36,
"edges": [CoreSiteworksRequestConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 66
}
}
}
smartDeviceNetwork
Type: SmartMeterDeviceNetworkType
URL: https://api.octopus.energy/v1/graphql/
Retrieve smartmeter devices connected to the same Home Area Network.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query devices
Arguments
| Name | Description |
|---|---|
|
The deviceId of one of the devices on the Home Area Network. |
Query
query SmartDeviceNetwork($deviceId: String!) {
smartDeviceNetwork(deviceId: $deviceId) {
id
smartDevices {
...SmartMeterDeviceTypeFragment
}
}
}
Variables
{
"deviceId": "97109530"
}
Response
{
"data": {
"smartDeviceNetwork": {
"id": "41649783",
"smartDevices": [SmartMeterDeviceType]
}
}
}
smartFlexDeviceSupplyPoint
Type: SmartFlexDeviceSupplyPointType
URL: https://api.octopus.energy/v1/graphql/
The supply point linked to the SmartFlex device.
Query Complexity: 2
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can view smartflex data
Rate Limits
| Key | Steps |
|---|---|
User |
['850/m'] |
Arguments
| Name | Description |
|---|---|
|
The SmartFlex device ID to get the supply point details for. |
Query
query SmartFlexDeviceSupplyPoint($smartFlexDeviceId: String) {
smartFlexDeviceSupplyPoint(smartFlexDeviceId: $smartFlexDeviceId) {
importSupplyPointId
smartFlexDeviceId
}
}
Variables
{
"smartFlexDeviceId": "30054490"
}
Response
{
"data": {
"smartFlexDeviceSupplyPoint": {
"importSupplyPointId": "17280320",
"smartFlexDeviceId": "14924223"
}
}
}
smartFlexOnboardingWizards
Type: [SmartFlexOnboardingWizard!]
URL: https://api.octopus.energy/v1/graphql/
A list of wizards for onboarding devices for an account and property.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4321: Serializer validation error.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number, e.g. A-12345678. |
|
Include cancelled wizards. |
|
Include completed wizards. |
|
Filters for onboarding wizards that can be resumed. List limits to one resumable wizard. |
|
Only list wizards for this property. |
|
To get a specific wizard by ID, if it exists. |
Query
query SmartFlexOnboardingWizards(
$accountNumber: String!,
$includeCancelled: Boolean,
$includeCompleted: Boolean,
$isResumable: Boolean,
$propertyId: Int,
$wizardId: ID
) {
smartFlexOnboardingWizards(
accountNumber: $accountNumber,
includeCancelled: $includeCancelled,
includeCompleted: $includeCompleted,
isResumable: $isResumable,
propertyId: $propertyId,
wizardId: $wizardId
) {
backendScreen {
... on ComponentListType {
...ComponentListTypeFragment
}
... on Dashboard {
...DashboardFragment
}
... on FormScreenType {
...FormScreenTypeFragment
}
... on GenericBackendScreen {
...GenericBackendScreenFragment
}
}
completedSteps {
...SmartFlexOnboardingStepInterfaceFragment
}
currentStep {
...SmartFlexOnboardingStepInterfaceFragment
}
deviceType
displayName
id
resumable {
...SmartFlexResumableFragment
}
}
}
Variables
{
"accountNumber": "A-C671CD98",
"includeCancelled": true,
"includeCompleted": true,
"isResumable": true,
"propertyId": 73533948,
"wizardId": "41525568"
}
Response
{
"data": {
"smartFlexOnboardingWizards": [
{
"backendScreen": ComponentListType,
"completedSteps": SmartFlexOnboardingStepInterface,
"currentStep": SmartFlexOnboardingStepInterface,
"deviceType": "BATTERIES",
"displayName": "democratic-force-into-technology-evidence",
"id": "48885522",
"resumable": SmartFlexResumable
}
]
}
}
smartMeterDataPreferences
Type: SmartMeterDataPreferencesType
URL: https://api.octopus.energy/v1/graphql/
Query Complexity: 1
Possible Errors:
- KT-CT-4023: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Query
query SmartMeterDataPreferences($accountNumber: String!) {
smartMeterDataPreferences(accountNumber: $accountNumber) {
readingFrequency
readingsAnalysisConsentProvided
readingsAnalysisConsentUpdatedDatetime
}
}
Variables
{
"accountNumber": "A-BB67957E"
}
Response
{
"data": {
"smartMeterDataPreferences": {
"readingFrequency": "DAILY",
"readingsAnalysisConsentProvided": true,
"readingsAnalysisConsentUpdatedDatetime": "1984-05-22T18:21:00.199359+00:00"
}
}
}
smartMeterTelemetry
Type: [SmartMeterTelemetryType]
URL: https://api.octopus.energy/v1/graphql/
Query telemetry data collected by the CAD associated with the provided ESME or GSME device ID.
If only the smart meter device ID is provided, the latest data available will be returned.
Additionally including the range options (start, end, and grouping) will return the data for that time period, at the desired granularity.
Query Complexity: 1
Possible Errors:
- KT-GB-4039: Unable to query smart meter telemetry data.
- KT-GB-4040: 'start', 'end', and 'grouping' must all be provided.
- KT-GB-4041: 'end' should be later than 'start'.
- KT-GB-4042: Too many requests. Please wait before trying again.
- KT-GB-4043: A network error occurred. Please try again.
- KT-GB-4050: Smart meter not found.
- KT-GB-4051: The start of the range is too far in the past.
- KT-GB-4056: No Device Network (HAN) record found for the device.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can view detailed usage
Rate Limits
| Key | Steps |
|---|---|
User |
['125/h'] |
Arguments
| Name | Description |
|---|---|
|
The ESME or GSME's EUI64 ID, e.g. '12-34-5A-FF-FF-6B-C7-89' |
|
The end time of the range of readings (exclusive), e.g. '2022-01-28T16:34:42+00:00'. If no UTC timezone offset is included, UTC (+00:00) will be assumed. |
|
The granularity of the returned data. The representative data item (e.g. consumption) for each group (e.g. every 5 minutes) will be the mean value over that period. |
|
The start time of the range of readings (inclusive), e.g. '2022-01-28T16:33:22+00:00'. If no UTC timezone offset is included, UTC (+00:00) will be assumed. |
Query
query SmartMeterTelemetry(
$deviceId: String!,
$end: DateTime,
$grouping: TelemetryGrouping,
$start: DateTime
) {
smartMeterTelemetry(
deviceId: $deviceId,
end: $end,
grouping: $grouping,
start: $start
) {
consumption
consumptionDelta
costDelta
costDeltaWithTax
demand
export
readAt
}
}
Variables
{
"deviceId": "93776306",
"end": "2010-05-14T09:17:05.825303+00:00",
"grouping": "TEN_SECONDS",
"start": "1973-08-22T14:23:11.680180+00:00"
}
Response
{
"data": {
"smartMeterTelemetry": [
{
"consumption": "1.0",
"consumptionDelta": "1.0",
"costDelta": "1.0",
"costDeltaWithTax": "1.0",
"demand": "1.0",
"export": "1.0",
"readAt": "2012-04-09T05:52:01.108319+00:00"
}
]
}
}
smartTariffComparison
Type: SmartTariffComparisonType
URL: https://api.octopus.energy/v1/graphql/
Compare consumption costs for different smart tariffs.
Query Complexity: 1
Possible Errors:
- KT-GB-10101: Electricity agreement not found.
- KT-GB-10102: Error while calculating consumption costs.
- KT-GB-10103: Not enough consumption data.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query property
Deprecated
The 'smartTariffComparison' field is deprecated.
The smart tariff comparison feature is no longer supported.
- Marked as deprecated on 2026-04-22.
- Scheduled for removal on or after 2026-05-15.
Arguments
| Name | Description |
|---|---|
|
MPAN of the import meter point linked to the meter. |
Query
query SmartTariffComparison($mpan: String) {
smartTariffComparison(mpan: $mpan) {
consumptionReadingsEndAt
consumptionReadingsStartAt
costComparisons {
...TariffComparisonTypeFragment
}
currentCost
currentCostWithTax
}
}
Variables
{
"mpan": "share-school-great-center-close"
}
Response
{
"data": {
"smartTariffComparison": {
"consumptionReadingsEndAt": "1979-12-31T11:37:54.131305+00:00",
"consumptionReadingsStartAt": "1971-05-14T21:08:24.107943+00:00",
"costComparisons": [TariffComparisonType],
"currentCost": 626.6,
"currentCostWithTax": 323.21
}
}
}
supplyPoint
Type: SupplyPointType
URL: https://api.octopus.energy/v1/graphql/
Get a supply point by its market specific id.
Query Complexity: 1
Possible Errors:
- KT-CT-4719: No supply point found for identifier provided.
- KT-CT-4722: Supply point readings API not configured.
- KT-CT-4723: Invalid market name provided.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The market specific supply point id. |
|
The name of the market in which this supply point exists. |
Query
query SupplyPoint(
$externalIdentifier: String!,
$marketName: String!
) {
supplyPoint(
externalIdentifier: $externalIdentifier,
marketName: $marketName
) {
devices {
...DevicesConnectionFragment
}
externalIdentifier
id
marketName
meterPoint {
... on ElectricityMeterPointType {
...ElectricityMeterPointTypeFragment
}
... on GasMeterPointType {
...GasMeterPointTypeFragment
}
}
property {
...PropertyTypeFragment
}
readings {
...ReadingsFragment
}
}
}
Variables
{
"externalIdentifier": "68672704",
"marketName": "camera-off-campaign-boy-likely"
}
Response
{
"data": {
"supplyPoint": {
"devices": DevicesConnection,
"externalIdentifier": "97154892",
"id": "52017627",
"marketName": "door-third-someone-call-board",
"meterPoint": ElectricityMeterPointType,
"property": PropertyType,
"readings": Readings
}
}
}
supplyPoints
Type: SupplyPointConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Get list of supply points.
Query Complexity: 2
Possible Errors:
- KT-CT-8801: Missing query parameters.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Filter meter points by account. |
|
|
|
|
|
|
|
|
|
Filter meter points by portfolio. |
Query
query SupplyPoints(
$accountNumber: String,
$after: String,
$before: String,
$first: Int,
$last: Int,
$portfolioNumber: String
) {
supplyPoints(
accountNumber: $accountNumber,
after: $after,
before: $before,
first: $first,
last: $last,
portfolioNumber: $portfolioNumber
) {
edgeCount
edges {
...SupplyPointConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-D6244268",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"first": 10,
"last": 10,
"portfolioNumber": "P-D40A6AFF"
}
Response
{
"data": {
"supplyPoints": {
"edgeCount": 38,
"edges": [SupplyPointConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 76
}
}
}
taktileBusinessTargeter
Type: TaktileBusinessTargeterResults
URL: https://api.octopus.energy/v1/graphql/
Acts as a proxy endpoint to request business details from Taktile API.
Query Complexity: 1
Possible Errors:
- KT-CT-10703: Input data is invalid.
- KT-CT-4177: Unauthorized.
- KT-GB-10701: Failed to request business details.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Input for requesting business details from Taktile API. |
Query
query TaktileBusinessTargeter($taktileBusinessTargeterInput: TaktileBusinessTargeterInput!) {
taktileBusinessTargeter(taktileBusinessTargeterInput: $taktileBusinessTargeterInput) {
searchResults {
...SearchResultFragment
}
}
}
Variables
{
"taktileBusinessTargeterInput": TaktileBusinessTargeterInput
}
Response
{
"data": {
"taktileBusinessTargeter": {
"searchResults": [SearchResult]
}
}
}
taskResult
Type: TaskResult
URL: https://api.octopus.energy/v1/graphql/
Get the status of a background task.
Query Complexity: 1
Possible Errors:
- KT-CT-10401: Task not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
Query
query TaskResult(
$accountNumber: String!,
$taskId: String!
) {
taskResult(
accountNumber: $accountNumber,
taskId: $taskId
) {
error
result
status
}
}
Variables
{
"accountNumber": "A-B2BB4FC6",
"taskId": "45244387"
}
Response
{
"data": {
"taskResult": {
"error": "prepare-century-increase-dream-operation",
"result": {"key": "value"},
"status": "STARTED"
}
}
}
termsAndConditionsForProduct
Type: GbrTermsAndConditionsType
URL: https://api.octopus.energy/v1/graphql/
Get the active terms and conditions for a product.
Query Complexity: 1
Possible Errors:
- KT-CT-8501: No active terms and conditions found for product.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
Query
query TermsAndConditionsForProduct($productCode: String!) {
termsAndConditionsForProduct(productCode: $productCode) {
brandCode
effectiveFrom
html
markdown
name
pdfUrl
version
}
}
Variables
{
"productCode": "size-suffer-accept-every-player"
}
Response
{
"data": {
"termsAndConditionsForProduct": {
"brandCode": "commercial-medical-western-sell-drive",
"effectiveFrom": "1998-05-21T23:23:14.286397+00:00",
"html": "tough-owner-a-be-energy",
"markdown": "fall-choice-any-according-whatever",
"name": "appear-house-boy-national-news",
"pdfUrl": "perhaps-very-which-sing-side",
"version": "various-consumer-than-million-team"
}
}
}
thirdPartyViewer
Type: ThirdPartyOrganizationType
URL: https://api.octopus.energy/v1/graphql/
The currently authenticated third party.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Query
query ThirdPartyViewer {
thirdPartyViewer {
name
permissions {
...ThirdPartyPermissionFragment
}
}
}
Response
{
"data": {
"thirdPartyViewer": {
"name": "lead-more-present-save-long",
"permissions": [ThirdPartyPermission]
}
}
}
trigger
Type: Trigger!
URL: https://api.octopus.energy/v1/graphql/
Get the details of a published trigger with a given ID.
Query Complexity: 3
Possible Errors:
- KT-CT-9904: Trigger not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The ID of the trigger. |
Query
query Trigger($triggerId: ID!) {
trigger(triggerId: $triggerId) {
accounts {
...AccountConnectionTypeConnectionFragment
}
accountsLinkedAt
createdAt
id
messages {
...MessageConnectionFragment
}
processingStatus
triggerTypeCode
}
}
Variables
{
"triggerId": "75763012"
}
Response
{
"data": {
"trigger": {
"accounts": AccountConnectionTypeConnection,
"accountsLinkedAt": "2021-10-04T02:42:42.284251+00:00",
"createdAt": "1974-09-25T15:00:30.178833+00:00",
"id": "31172038",
"messages": MessageConnection,
"processingStatus": "UNPROCESSED",
"triggerTypeCode": "energy-that-effect-television-really"
}
}
}
urls
Type: Urls
URL: https://api.octopus.energy/v1/graphql/
URLs for an account.
Query Complexity: 1
Possible Errors:
- KT-CT-4123: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number of the URLs' account. |
Query
query Urls($accountNumber: String!) {
urls(accountNumber: $accountNumber) {
bookSmartMeterInstallation
}
}
Variables
{
"accountNumber": "A-D7177ACB"
}
Response
{
"data": {
"urls": {
"bookSmartMeterInstallation": "kid-budget-popular-inside-feel"
}
}
}
useSmartPearForInstalls
Type: Boolean
URL: https://api.octopus.energy/v1/graphql/
Retrieve a boolean which is True if the meter device is on SmartPear, False if on uSmart.
Query Complexity: 1
Possible Errors:
- KT-GB-4050: Smart meter not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query devices
Arguments
| Name | Description |
|---|---|
|
The deviceId of one of the meters on the Home Area Network. |
Query
query UseSmartPearForInstalls($deviceId: String!) {
useSmartPearForInstalls(deviceId: $deviceId)
}
Variables
{
"deviceId": "38819988"
}
Response
{
"data": {
"useSmartPearForInstalls": true
}
}
validateBankAccount
Type: ValidateBankAccount
URL: https://api.octopus.energy/v1/graphql/
Validate a bank account.
Query Complexity: 1
Possible Errors:
- KT-GB-3913: The vendor is currently unavailable.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Query
query ValidateBankAccount(
$accountNumber: String!,
$sortCode: String!,
$vendor: PaymentsVendorChoices
) {
validateBankAccount(
accountNumber: $accountNumber,
sortCode: $sortCode,
vendor: $vendor
) {
bankName
branch
county
line1
line2
line3
line4
postcode
town
}
}
Variables
{
"accountNumber": "A-9DF63824",
"sortCode": "knowledge-yeah-someone-picture-bill",
"vendor": "SMARTDEBIT"
}
Response
{
"data": {
"validateBankAccount": {
"bankName": "expect-have-director-couple-then",
"branch": "world-system-every-challenge-season",
"county": "prove-account-physical-knowledge-control",
"line1": "since-set-on-wife-clear",
"line2": "radio-alone-room-interview-paper",
"line3": "star-effort-skin-year-around",
"line4": "talk-learn-effort-easy-yourself",
"postcode": "program-character-even-city-book",
"town": "through-sell-most-bar-space"
}
}
}
validateReferralClaimCode
Type: ReferralClaimCodeType
URL: https://api.octopus.energy/v1/graphql/
Validate referral claim code.
Query Complexity: 1
Possible Errors:
- KT-CT-6724: Referral claim code not found.
- KT-CT-6726: Referral claim code has already been redeemed.
- KT-CT-6727: Referral claim code is not available.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['5/m'] |
Deprecated
The 'validateReferralClaimCode' field is deprecated.
Use the global territories.common.referrals.validateReferralCode query instead.
- Marked as deprecated on 2025-10-20.
- Scheduled for removal on or after 2026-10-20.
Arguments
| Name | Description |
|---|---|
|
Referral claim code value. |
Query
query ValidateReferralClaimCode($value: String!) {
validateReferralClaimCode(value: $value) {
accountReferral {
...ReferralTypeFragment
}
createdAt
id
isValid
referralScheme {
...ReferralSchemeTypeFragment
}
value
}
}
Variables
{
"value": "among-site-western-under-environmental"
}
Response
{
"data": {
"validateReferralClaimCode": {
"accountReferral": ReferralType,
"createdAt": "1976-02-01T19:01:10.689065+00:00",
"id": 22881842,
"isValid": true,
"referralScheme": ReferralSchemeType,
"value": "talk-action-need-those-traditional"
}
}
}
validateReferralCode
Type: ReferralClaimCodeType
URL: https://api.octopus.energy/v1/graphql/
Validate referral claim code.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Rate Limits
| Key | Steps |
|---|---|
Ip |
['5/m'] |
Arguments
| Name | Description |
|---|---|
|
Referral claim code value. |
Query
query ValidateReferralCode($value: String!) {
validateReferralCode(value: $value) {
accountReferral {
...ReferralTypeFragment
}
createdAt
id
isValid
referralScheme {
...ReferralSchemeTypeFragment
}
value
}
}
Variables
{
"value": "century-whole-because-actually-never"
}
Response
{
"data": {
"validateReferralCode": {
"accountReferral": ReferralType,
"createdAt": "1980-12-07T03:03:18.652094+00:00",
"id": 19209536,
"isValid": true,
"referralScheme": ReferralSchemeType,
"value": "show-part-might-claim-cover"
}
}
}
vehicleChargingPreferences
Type: VehicleChargingPreferencesType
URL: https://api.octopus.energy/v1/graphql/
Vehicle charging preference details.
Query Complexity: 3
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4339: Your device charging preferences could not be fetched.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
Rate Limits
| Key | Steps |
|---|---|
User |
['300/h'] |
Deprecated
The 'vehicleChargingPreferences' field is deprecated.
Please use 'devices.preferences' instead.
- Marked as deprecated on 2024-04-23.
- Scheduled for removal on or after 2026-03-01.
You can read more about this deprecation on:
https://announcements.kraken.tech/announcements/public/675/
Arguments
| Name | Description |
|---|---|
|
Query
query VehicleChargingPreferences($accountNumber: String!) {
vehicleChargingPreferences(accountNumber: $accountNumber) {
maximumSocPercentage
minimumSocPercentage
weekdayTargetSoc
weekdayTargetTime
weekendTargetSoc
weekendTargetTime
}
}
Variables
{
"accountNumber": "A-AC996BB4"
}
Response
{
"data": {
"vehicleChargingPreferences": {
"maximumSocPercentage": 85,
"minimumSocPercentage": 44,
"weekdayTargetSoc": 98,
"weekdayTargetTime": "rest-budget-value-in-loss",
"weekendTargetSoc": 4,
"weekendTargetTime": "through-however-skin-coach-official"
}
}
}
verificationStatus
Type: EmailVerificationStatus
URL: https://api.octopus.energy/v1/graphql/
Check the verification status of a given email address.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The email address to be checked. |
Query
query VerificationStatus($email: String!) {
verificationStatus(email: $email) {
email
status
}
}
Variables
{
"email": "feel-benefit-note-event-forward"
}
Response
{
"data": {
"verificationStatus": {
"email": "quite-school-or-appear-party",
"status": "NOT_SENT"
}
}
}
viewer
Type: AccountUserType
URL: https://api.octopus.energy/v1/graphql/
The currently authenticated user.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can view account number
OR Can view account type
OR Can view account user permissions
OR Can view sensitive customer information
Query
query Viewer {
viewer {
accounts {
...AccountInterfaceFragment
}
accountUserRoles {
...AccountUserRoleTypeFragment
}
address {
...RichAddressTypeFragment
}
alternativePhoneNumbers
businesses {
...BusinessConnectionTypeConnectionFragment
}
consents {
...ConsentTypeFragment
}
createdAt
dateOfBirth
details {
...AccountUserDetailTypeFragment
}
email
familyName
fullName
givenName
hasFamilyIssues
holdMusicChoices {
...TrackOptionTypeFragment
}
id
isActive
isDeceased
isInHardship
isOptedInToWof
label
landline
liveSecretKey
mobile
number
paymentMethods {
...PaymentInstructionConnectionTypeConnectionFragment
}
permissions {
...AccountUserPermissionFragment
}
portfolioIds
portfolios {
...PortfolioConnectionTypeConnectionFragment
}
portfolioUserRoles {
...PortfolioUserRoleTypeFragment
}
preferences {
...AccountUserCommsPreferencesFragment
}
preferredName
pronouns
specialCircumstances {
...SpecialCircumstancesTypeFragment
}
title
}
}
Response
{
"data": {
"viewer": {
"accounts": AccountInterface,
"accountUserRoles": [AccountUserRoleType],
"address": RichAddressType,
"alternativePhoneNumbers": "under-case-purpose-central-economic",
"businesses": BusinessConnectionTypeConnection,
"consents": [ConsentType],
"createdAt": "1970-09-26T10:22:17.065497+00:00",
"dateOfBirth": "2001-08-15",
"details": [AccountUserDetailType],
"email": "present-third-couple-quite-phone",
"familyName": "Welch",
"fullName": "upon-member-one-our-hit",
"givenName": "Kristin",
"hasFamilyIssues": true,
"holdMusicChoices": [TrackOptionType],
"id": "17931766",
"isActive": true,
"isDeceased": true,
"isInHardship": true,
"isOptedInToWof": true,
"label": "big-know-natural-personal-above",
"landline": "lose-job-test-while-north",
"liveSecretKey": "gas-moment-professor-place-you",
"mobile": "manage-produce-interview-local-nearly",
"number": "alone-seat-note-grow-those",
"paymentMethods": PaymentInstructionConnectionTypeConnection,
"permissions": [AccountUserPermission],
"portfolioIds": "78083862",
"portfolios": PortfolioConnectionTypeConnection,
"portfolioUserRoles": [PortfolioUserRoleType],
"preferences": AccountUserCommsPreferences,
"preferredName": "certainly-choose-relationship-region-color",
"pronouns": "out-either-Mrs-wife-let",
"specialCircumstances": SpecialCircumstancesType,
"title": "beat-mouth-key-daughter-tough"
}
}
}
voiceCampaign
Type: VoiceCampaignType!
URL: https://api.octopus.energy/v1/graphql/
Get the voice campaign for a given ID.
Query Complexity: 2
Possible Errors:
- KT-CT-11501: Voice campaign not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query voice campaigns
Arguments
| Name | Description |
|---|---|
|
The campaign ID. |
Query
query VoiceCampaign($campaignId: String!) {
voiceCampaign(campaignId: $campaignId) {
campaignItems {
...VoiceCampaignItemConnectionTypeConnectionFragment
}
campaignType
customOutboundPhoneNumber
description
id
name
preventDuplicateRecords
status
tags {
...CallTagConnectionTypeConnectionFragment
}
}
}
Variables
{
"campaignId": "20885948"
}
Response
{
"data": {
"voiceCampaign": {
"campaignItems": VoiceCampaignItemConnectionTypeConnection,
"campaignType": "PREVIEW",
"customOutboundPhoneNumber": "research-two-oil-five-state",
"description": "crime-human-certain-space-season",
"id": "71192579",
"name": "notice-authority-not-hear-soon",
"preventDuplicateRecords": true,
"status": "ACTIVE",
"tags": CallTagConnectionTypeConnection
}
}
}
voiceCampaigns
Type: VoiceCampaignConnectionTypeConnection!
URL: https://api.octopus.energy/v1/graphql/
Get voice campaigns.
Query Complexity: 2
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query voice campaigns
Arguments
| Name | Description |
|---|---|
|
|
|
|
|
Filter by campaign type. |
|
|
|
|
|
Filter by campaign name. |
|
Filter by campaign status. |
Query
query VoiceCampaigns(
$after: String,
$before: String,
$campaignType: TypeOfVoiceCampaign,
$first: Int,
$last: Int,
$name: String,
$status: CampaignStatus
) {
voiceCampaigns(
after: $after,
before: $before,
campaignType: $campaignType,
first: $first,
last: $last,
name: $name,
status: $status
) {
edgeCount
edges {
...VoiceCampaignConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"campaignType": "PREVIEW",
"first": 10,
"last": 10,
"name": "product-town-they-pretty-best",
"status": "ACTIVE"
}
Response
{
"data": {
"voiceCampaigns": {
"edgeCount": 23,
"edges": [VoiceCampaignConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 64
}
}
}
vouchersBalanceDetail
Type: VouchersBalanceDetail
URL: https://api.octopus.energy/v1/graphql/
Query the detail of vouchers balance for an account.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-4178: No account found with given account number.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number. |
Query
query VouchersBalanceDetail($accountNumber: ID!) {
vouchersBalanceDetail(accountNumber: $accountNumber) {
redeemableInFuture
redeemableToday
}
}
Variables
{
"accountNumber": "A-E74FB3EF"
}
Response
{
"data": {
"vouchersBalanceDetail": {
"redeemableInFuture": 54,
"redeemableToday": 78
}
}
}
vouchersForAccount
Type: VoucherPurchaseConnectionTypeConnection
URL: https://api.octopus.energy/v1/graphql/
Query the voucher purchases for an account.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
- KT-CT-3820: Received both ledger ID and number.
- KT-CT-4178: No account found with given account number.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number. |
|
|
|
An optional date to limit the response to vouchers that are available before the particular date (exclusive). |
|
An optional date to limit the response to vouchers that are available from the particular date (inclusive) onwards. |
|
|
|
An optional list of display names to exclude from the results (case-insensitive). |
|
Whether to exclude refunded vouchers from the response. By default, refunded vouchers will be included in the response. |
|
|
|
|
|
An optional date to limit the response to vouchers that have been purchased before the particular date (exclusive). |
|
An optional date to limit the response to vouchers that have been purchased from the particular date (inclusive) onwards. |
|
Whether to only return vouchers that can be redeemable. |
Query
query VouchersForAccount(
$accountNumber: ID!,
$after: String,
$availableBeforeDate: Date,
$availableFromDate: Date,
$before: String,
$excludeByDisplayName: [String],
$excludeRefunded: Boolean,
$first: Int,
$last: Int,
$purchasedBeforeDate: Date,
$purchasedFromDate: Date,
$redeemableOnly: Boolean!
) {
vouchersForAccount(
accountNumber: $accountNumber,
after: $after,
availableBeforeDate: $availableBeforeDate,
availableFromDate: $availableFromDate,
before: $before,
excludeByDisplayName: $excludeByDisplayName,
excludeRefunded: $excludeRefunded,
first: $first,
last: $last,
purchasedBeforeDate: $purchasedBeforeDate,
purchasedFromDate: $purchasedFromDate,
redeemableOnly: $redeemableOnly
) {
edgeCount
edges {
...VoucherPurchaseConnectionTypeEdgeFragment
}
pageInfo {
...PageInfoFragment
}
totalCount
}
}
Variables
{
"accountNumber": "A-B76E13D7",
"after": "YXJyYXljb25uZWN0aW9uOjEw=",
"availableBeforeDate": "1977-12-16",
"availableFromDate": "1988-09-27",
"before": "YXJyYXljb25uZWN0aW9uOjEw=",
"excludeByDisplayName": "billion-run-there-you-event",
"excludeRefunded": true,
"first": 10,
"last": 10,
"purchasedBeforeDate": "2025-09-12",
"purchasedFromDate": "2004-02-02",
"redeemableOnly": true
}
Response
{
"data": {
"vouchersForAccount": {
"edgeCount": 94,
"edges": [VoucherPurchaseConnectionTypeEdge],
"pageInfo": PageInfo,
"totalCount": 57
}
}
}
wanCoverage
Type: WANCoverageStrengths
URL: https://api.octopus.energy/v1/graphql/
Likelihood that a smart meter at the given postcode and optional address identifier will get a stable network connection.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query wan data
Arguments
| Name | Description |
|---|---|
|
The address identifier to search for. |
|
Postcode to search the coverage for |
|
The property ID to search for. |
Query
query WanCoverage(
$addressIdentifier: String,
$postcode: String!,
$propertyId: ID
) {
wanCoverage(
addressIdentifier: $addressIdentifier,
postcode: $postcode,
propertyId: $propertyId
)
}
Variables
{
"addressIdentifier": "66272569",
"postcode": "contain-place-PM-nothing-world",
"propertyId": "93193483"
}
Response
{
"data": {
"wanCoverage": "HIGH"
}
}
wanCoverageDetail
Type: [WanCoverageDetail]
URL: https://api.octopus.energy/v1/graphql/
Detailed WAN coverage report for a given post code and optional address identifier.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
OR Can query wan data
Arguments
| Name | Description |
|---|---|
|
|
|
The postcode to search for. |
|
The property ID to search for. |
Query
query WanCoverageDetail(
$addressIdentifier: String,
$postcode: String!,
$propertyId: ID
) {
wanCoverageDetail(
addressIdentifier: $addressIdentifier,
postcode: $postcode,
propertyId: $propertyId
) {
additionalInformation
addressIdentifier
anticipatedCoverageAt
auxiliaryEquipment
connectivityLikelihood
isCoverageAvailable
postcode
wanTechnology
}
}
Variables
{
"addressIdentifier": "10133032",
"postcode": "identify-right-particularly-against-process",
"propertyId": "63927466"
}
Response
{
"data": {
"wanCoverageDetail": [
{
"additionalInformation": "author-child-plant-tell-bad",
"addressIdentifier": "59916777",
"anticipatedCoverageAt": "feeling-contain-paper-conference-challenge",
"auxiliaryEquipment": "wide-learn-type-design-expert",
"connectivityLikelihood": "contain-security-development-good-follow",
"isCoverageAvailable": true,
"postcode": "billion-describe-concern-yard-environment",
"wanTechnology": "individual-issue-yourself-life-data"
}
]
}
}
weeklyUsageInsights
Type: WeeklyUsageInsightsType
URL: https://api.octopus.energy/v1/graphql/
Get account status information given its number.
Query Complexity: 1
Possible Errors:
- KT-CT-1111: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Arguments
| Name | Description |
|---|---|
|
The account number to search for. |
Query
query WeeklyUsageInsights($accountNumber: String!) {
weeklyUsageInsights(accountNumber: $accountNumber) {
accountId
accountNumber
achievedCarbonIndex
achievedCarbonRank
achievedCarbonRate
apiGspGroupName
carbonGrams
consumptionKwh
gspGroupId
hasFullReadings
isLatestWeek
meterPointId
mpan
numberPeriods
periodEnd
periodStart
propertyId
weekStart
}
}
Variables
{
"accountNumber": "A-95B4A9E6"
}
Response
{
"data": {
"weeklyUsageInsights": {
"accountId": 99447354,
"accountNumber": "A-4125BCC8",
"achievedCarbonIndex": "VERY_LOW",
"achievedCarbonRank": "later-create-outside-cultural-authority",
"achievedCarbonRate": 47.72,
"apiGspGroupName": "conference-score-let-admit-tend",
"carbonGrams": 742.4,
"consumptionKwh": "anyone-where-them-minute-leave",
"gspGroupId": "71264107",
"hasFullReadings": "partner-television-deep-statement-between",
"isLatestWeek": "situation-central-red-beyond-part",
"meterPointId": 94091821,
"mpan": "newspaper-four-agreement-pick-defense",
"numberPeriods": "focus-series-strategy-near-particularly",
"periodEnd": "1992-12-14T00:25:14.581589+00:00",
"periodStart": "2017-01-31T19:21:01.861319+00:00",
"propertyId": 67057585,
"weekStart": "2010-06-02T21:36:06.739313+00:00"
}
}
}
wheelOfFortuneSegments
Type: WheelSegmentsType!
URL: https://api.octopus.energy/v1/graphql/
Retrieve the segments to be displayed on the Wheel of Fortune.
This field requires the Authorization header to be set.
Query Complexity: 1
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
Deprecated
The 'wheelOfFortuneSegments' field is deprecated.
We're migrating the system the Wheel of Fortune runs on. Octopus Energy UK customers can find the new API under api.backend.octopus.energy/v1/graphql/
- Marked as deprecated on 2025-06-24.
- Scheduled for removal on or after 2025-09-24.
Query
query WheelOfFortuneSegments {
wheelOfFortuneSegments {
segments
}
}
Response
{
"data": {
"wheelOfFortuneSegments": {
"segments": 62
}
}
}
wheelOfFortuneSpins
Type: AvailableSpinsType!
URL: https://api.octopus.energy/v1/graphql/
Retrieve the number of available Wheel of Fortune spins, per energy type, of an account by the account number.
This field requires the Authorization header to be set.
Query Complexity: 1
Possible Errors:
- KT-CT-7023: Unauthorized.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can access customer queries
Deprecated
The 'wheelOfFortuneSpins' field is deprecated.
We're migrating the system the Wheel of Fortune runs on. Octopus Energy UK customers can find the new API under api.backend.octopus.energy/v1/graphql/
- Marked as deprecated on 2026-02-20.
- Scheduled for removal on or after 2026-04-20.
Arguments
| Name | Description |
|---|---|
|
The account number for which the available spins are gathered. |
Query
query WheelOfFortuneSpins($accountNumber: String!) {
wheelOfFortuneSpins(accountNumber: $accountNumber) {
electricity {
...SupplyTypeSpecificSpinsTypeFragment
}
gas {
...SupplyTypeSpecificSpinsTypeFragment
}
}
}
Variables
{
"accountNumber": "A-5D8B52E7"
}
Response
{
"data": {
"wheelOfFortuneSpins": {
"electricity": SupplyTypeSpecificSpinsType,
"gas": SupplyTypeSpecificSpinsType
}
}
}
workSchedule
Type: WorkScheduleType!
URL: https://api.octopus.energy/v1/graphql/
Get the work schedule with the given identifier.
Query Complexity: 1
Possible Errors:
- KT-CT-11804: Work schedule not found.
Allowed Viewers:
| Viewer type | Allowed? |
|---|---|
| Customer | |
| Third party | |
Required Permissions:
Can query work schedules
Arguments
| Name | Description |
|---|---|
|
The identifier of the work schedule (also known as the 'slug'). |
Query
query WorkSchedule($identifier: String!) {
workSchedule(identifier: $identifier) {
identifier
isOpen
isPublicHoliday
name
openOrClosedReason
}
}
Variables
{
"identifier": "25961310"
}
Response
{
"data": {
"workSchedule": {
"identifier": "16433738",
"isOpen": true,
"isPublicHoliday": true,
"name": "way-whole-thing-agree-TV",
"openOrClosedReason": "CLOSED_DUE_TO_PUBLIC_HOLIDAY"
}
}
}