Command reference

Analytics and transactions

Akedly CLI command reference: Analytics and transactions.

Build with AI agents

transactions status

Inspect one OTP transaction or V2 widget attempt, or resolve a small batch of identifiers.

When to use

When a send result is uncertain, to inspect current lifecycle status, or to resume a single async verification wait.

How it works

API-key POST to status endpoint; accepts exactly one single ID or batch ID flags (1–50 total). --wait is single only and polls every three seconds, bounded by expiry/default 600 seconds.

Prerequisites

A configured API key with access to status lookups; the transaction or attempt identifier must come from a prior send/attempt.

Expected outcome

Returns the backend transaction or widget-attempt status layout without normalization; waited successful responses add waited outcome/polls/elapsedSeconds. Payloads can include private OTP fields.

Next steps

Use the returned state to decide whether to proceed; after timeout inspect again rather than initiating another billable send.

Usage

akedly transactions status

Inspect this command offline before preparing an operation:

akedly describe "transactions status" --output json

Flags

Flag	Type	Enum / range	Required	Description
`--ksa`	boolean switch	—	no	Select the KSA deployment.
`--transaction-id`	text	—	no	Command-specific option; see the full command details below. Manifest body field: transactionID.
`--attempt-id`	text	—	no	Command-specific option; see the full command details below. Manifest body field: attemptId.
`--transaction-ids`	text	—	no	Command-specific option; see the full command details below. Manifest body field: transactionIDs.
`--attempt-ids`	text	—	no	Command-specific option; see the full command details below. Manifest body field: attemptIds.
`--api-key`	text	—	no	Select a saved API key by its eight-character prefix; never supply a full Secret.
`--dry-run`	boolean switch	—	no	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--wait`	boolean switch	—	no	Command-specific option; see the full command details below.
`--timeout`	seconds	—	no	Command-specific option; see the full command details below.
`--help`	boolean switch	—	no	Show offline command help.
`--output`	enum	json \| human	no	Select JSON or human output.
`--fields`	dot-paths	—	no	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: api-key. Permission: none declared.

Server request: POST /transactions/status; /transactions/status/batch.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

idempotent: Idempotent requests retry network errors and HTTP 429/502/503/504, at most 3 tries, waiting for cooldownSeconds, retryAfter or the Retry-After header (otherwise 1 second) between tries, up to 30 seconds; a longer requested wait is returned as the error.

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Use AKEDLY_API_KEY or a saved API key selected with --api-key <prefix>; CLI Logins are not used. Look up one --transaction-id or --attempt-id, or a batch with --transaction-ids and/or --attempt-ids (1–50 ids total). Single and batch flags cannot mix. Responses may include live OTP fields; keep output private. Limit: 300 ids per minute per account; retries count again. Dry runs send nothing. --wait supports single lookups only, polls every 3 seconds until verification or expiry, and shares the account budget with other waits. --timeout requires --wait and caps the wait; without an expiry the default is 600 seconds.

Worked examples

Examples are synthetic illustrations, never live account records. Replace resource IDs with your own authorized resources. Secret values are omitted here; redacted examples illustrate the shape and are not schema-validation fixtures.

Synthetic offline fixture

Inspect one OTP transaction or V2 widget attempt, or resolve a small batch of identifiers.

akedly transactions status --transaction-id 9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "mainTransaction": {
      "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
      "status": "Pending",
      "verificationAddress": {
        "phoneNumber": "+201234567890"
      },
      "expirationDate": "2026-10-29T12:05:00.000Z"
    },
    "transactionReq": {
      "_id": "65a1b2c3d4e5f67890123456",
      "status": "Pending",
      "verified": false
    }
  }
}

All IDs, destination, company, dates, callback URL and payload values are synthetic fixtures; example.invalid is reserved for documentation. Do not paste a real OTP, phone, API key, widget Secret, token, or account identifier into an agent test or shared output.

This worked response is illustrative only and was not executed against an account.

Additional command forms

akedly transactions status --transaction-id <id>

akedly transactions status --transaction-ids <id1>,<id2>

Input and file contracts

The contract below describes typed arguments, file formats, validation boundaries and API mappings. Boolean switches take no value; numeric and comma-separated values are each passed as one argument. Read prerequisites and full command details for state-dependent requirements.

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "transaction-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "transactionID",
          "transform": "identity",
          "routeIndex": 0,
          "role": "body",
          "input": "transaction-id",
          "contributors": [
            "transaction-id"
          ]
        }
      ]
    },
    {
      "name": "attempt-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "attemptId",
          "transform": "identity",
          "routeIndex": 0,
          "role": "body",
          "input": "attempt-id",
          "contributors": [
            "attempt-id"
          ]
        }
      ]
    },
    {
      "name": "transaction-ids",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "transactionIDs",
          "transform": "split-trim",
          "routeIndex": 1,
          "role": "body",
          "input": "transaction-ids",
          "contributors": [
            "transaction-ids"
          ]
        }
      ]
    },
    {
      "name": "attempt-ids",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "attemptIds",
          "transform": "split-trim",
          "routeIndex": 1,
          "role": "body",
          "input": "attempt-ids",
          "contributors": [
            "attempt-ids"
          ]
        }
      ]
    },
    {
      "name": "api-key",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{8}$"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "api-key-prefix-selection",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "api-key",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "api-key-prefix-selection",
          "contributors": [
            "api-key"
          ]
        }
      ],
      "validation": {
        "syntax": "Eight hexadecimal characters naming a saved key prefix. Never put the full API-key Secret on the command line; use AKEDLY_API_KEY for a full credential."
      }
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    },
    {
      "name": "wait",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "wait",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "wait",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "wait",
          "contributors": [
            "wait"
          ]
        }
      ]
    },
    {
      "name": "timeout",
      "schema": {
        "type": "string",
        "pattern": "^(?:0+\\.\\d*[1-9]\\d*|0*(?:[1-9]\\d{0,3}|[1-7]\\d{4}|8[0-5]\\d{3}|86[0-3]\\d{2})(?:\\.\\d+)?|0*86400(?:\\.0+)?)$"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "timeout",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "timeout",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "timeout",
          "contributors": [
            "timeout"
          ]
        }
      ],
      "validation": {
        "syntax": "Positive decimal seconds, maximum 86400; integers and fractions are accepted.",
        "parsedValueSchema": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 86400
        }
      }
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": [
      "/transactions/status",
      "/transactions/status/batch"
    ],
    "query": {},
    "body": {
      "transaction-id": [
        {
          "path": "transactionID",
          "transform": "identity",
          "routeIndex": 0,
          "role": "body",
          "input": "transaction-id",
          "contributors": [
            "transaction-id"
          ]
        }
      ],
      "attempt-id": [
        {
          "path": "attemptId",
          "transform": "identity",
          "routeIndex": 0,
          "role": "body",
          "input": "attempt-id",
          "contributors": [
            "attempt-id"
          ]
        }
      ],
      "transaction-ids": [
        {
          "path": "transactionIDs",
          "transform": "split-trim",
          "routeIndex": 1,
          "role": "body",
          "input": "transaction-ids",
          "contributors": [
            "transaction-ids"
          ]
        }
      ],
      "attempt-ids": [
        {
          "path": "attemptIds",
          "transform": "split-trim",
          "routeIndex": 1,
          "role": "body",
          "input": "attempt-ids",
          "contributors": [
            "attempt-ids"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

Status lookups are constrained by the API key’s pipeline scope. A single out-of-scope lookup returns API_KEY_SCOPE_DENIED; batch responses keep per-ID success/error outcomes in transactions and attempts arrays, so inspect each item. Batch itemCounts are server log details, not response fields.

For V1/V1.2 transaction lookups, transactionReq can be null before an activation request exists, and a V1.2 passkey replay synthesizes a request without Mongo _id. For attempt replay, widgetAttempt.status reflects persisted WidgetAttempt lifecycle states: pending, captcha_solved, otp_requested, verified, failed, or expired.

In-scope attempt data can include application-provided publicMetadata and privateMetadata. Treat both as private output; never copy real metadata or OTP values into shared examples.

The V1/V1.2 transactionReq union distinguishes an actual OTP request (with required Mongo _id and status), a synthesized V1.2 passkey request (verificationMethod=passkey and isTest, with no _id), or null before an activation request exists.

An actual OTP transaction request may contain inputOTP; treat returned request objects as sensitive even though examples use synthetic values.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "oneOf": [
      {
        "type": "object",
        "properties": {
          "status": {
            "const": "success"
          },
          "data": {
            "type": "object",
            "properties": {
              "mainTransaction": {
                "type": "object",
                "properties": {
                  "transactionID": {
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "Pending",
                      "Successful",
                      "Failed",
                      "Skipped"
                    ]
                  },
                  "verificationAddress": {
                    "type": "object",
                    "properties": {
                      "phoneNumber": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  },
                  "expirationDate": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "creationDate": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "updateDate": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "reason": {
                    "type": "string"
                  }
                },
                "required": [
                  "transactionID",
                  "status"
                ],
                "additionalProperties": true
              },
              "transactionReq": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "_id": {
                        "type": "string"
                      },
                      "mainTransactionID": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      },
                      "isTest": {
                        "type": "boolean"
                      },
                      "channels": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "sentVerificationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "inputOTP": {
                        "type": "string"
                      },
                      "verificationDate": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time"
                      },
                      "creationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "expirationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "verificationMethod": {
                        "type": "string"
                      },
                      "reason": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "_id",
                      "status"
                    ],
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string"
                      },
                      "verificationMethod": {
                        "const": "passkey"
                      },
                      "isTest": {
                        "type": "boolean"
                      },
                      "reason": {
                        "type": "string"
                      },
                      "verificationDate": {
                        "type": "string",
                        "format": "date-time"
                      }
                    },
                    "required": [
                      "status",
                      "verificationMethod",
                      "isTest"
                    ],
                    "not": {
                      "required": [
                        "_id"
                      ]
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "whatsapp": {
                "type": "object",
                "properties": {
                  "status": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "additionalProperties": true
              }
            },
            "required": [
              "mainTransaction",
              "transactionReq"
            ],
            "additionalProperties": true
          },
          "waited": {
            "type": "object",
            "properties": {
              "outcome": {
                "const": "verified"
              },
              "polls": {
                "type": "integer"
              },
              "elapsedSeconds": {
                "type": "number"
              }
            },
            "required": [
              "outcome",
              "polls",
              "elapsedSeconds"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "status",
          "data"
        ],
        "additionalProperties": true
      },
      {
        "type": "object",
        "properties": {
          "status": {
            "const": "success"
          },
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "enum": [
                  "pending",
                  "success",
                  "failed"
                ]
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              },
              "widgetAttempt": {
                "type": "object",
                "properties": {
                  "attemptId": {
                    "type": "string"
                  },
                  "widgetId": {
                    "type": "string"
                  },
                  "userId": {
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "pending",
                      "captcha_solved",
                      "otp_requested",
                      "verified",
                      "failed",
                      "expired"
                    ]
                  },
                  "isTest": {
                    "type": "boolean"
                  },
                  "verificationAddress": {
                    "type": "object",
                    "properties": {
                      "phoneNumber": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "email": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "additionalProperties": true
                  },
                  "otpConfig": {
                    "type": "object",
                    "properties": {
                      "digits": {
                        "type": "integer"
                      },
                      "resendCount": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": true
                  },
                  "publicMetadata": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "captchaVerifiedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "otpRequestedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "completedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "attemptId",
                  "status",
                  "verificationAddress",
                  "otpConfig",
                  "createdAt",
                  "expiresAt"
                ],
                "additionalProperties": true
              },
              "transaction": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "transactionID": {
                        "type": "string"
                      },
                      "status": {
                        "enum": [
                          "Pending",
                          "Successful",
                          "Failed",
                          "Skipped"
                        ]
                      },
                      "verificationAddress": {
                        "type": "object",
                        "properties": {
                          "phoneNumber": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      },
                      "expirationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "creationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "updateDate": {
                        "anyOf": [
                          {
                            "type": "string",
                            "format": "date-time"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "reason": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "transactionID",
                      "status"
                    ],
                    "additionalProperties": true
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "transactionReq": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "_id": {
                        "type": "string"
                      },
                      "mainTransactionID": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string"
                      },
                      "isTest": {
                        "type": "boolean"
                      },
                      "channels": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "sentVerificationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "inputOTP": {
                        "type": "string"
                      },
                      "verificationDate": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time"
                      },
                      "creationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "expirationDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "verificationMethod": {
                        "type": "string"
                      },
                      "reason": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "_id",
                      "status"
                    ],
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string"
                      },
                      "verificationMethod": {
                        "const": "passkey"
                      },
                      "isTest": {
                        "type": "boolean"
                      },
                      "reason": {
                        "type": "string"
                      },
                      "verificationDate": {
                        "type": "string",
                        "format": "date-time"
                      }
                    },
                    "required": [
                      "status",
                      "verificationMethod",
                      "isTest"
                    ],
                    "not": {
                      "required": [
                        "_id"
                      ]
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "publicMetadata": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "privateMetadata": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": true
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message"
                ],
                "additionalProperties": true
              },
              "entries": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "enum": [
                        "pending",
                        "success",
                        "failed"
                      ]
                    },
                    "transaction": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "transactionID": {
                              "type": "string"
                            },
                            "status": {
                              "enum": [
                                "Pending",
                                "Successful",
                                "Failed",
                                "Skipped"
                              ]
                            },
                            "verificationAddress": {
                              "type": "object",
                              "properties": {
                                "phoneNumber": {
                                  "type": "string"
                                },
                                "email": {
                                  "type": "string"
                                }
                              },
                              "additionalProperties": true
                            },
                            "expirationDate": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "creationDate": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "updateDate": {
                              "anyOf": [
                                {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "reason": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "transactionID",
                            "status"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "transactionReq": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "_id": {
                              "type": "string"
                            },
                            "mainTransactionID": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "isTest": {
                              "type": "boolean"
                            },
                            "channels": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "sentVerificationDate": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "inputOTP": {
                              "type": "string"
                            },
                            "verificationDate": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "format": "date-time"
                            },
                            "creationDate": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "expirationDate": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "verificationMethod": {
                              "type": "string"
                            },
                            "reason": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "_id",
                            "status"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "object",
                          "properties": {
                            "status": {
                              "type": "string"
                            },
                            "verificationMethod": {
                              "const": "passkey"
                            },
                            "isTest": {
                              "type": "boolean"
                            },
                            "reason": {
                              "type": "string"
                            },
                            "verificationDate": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "status",
                            "verificationMethod",
                            "isTest"
                          ],
                          "not": {
                            "required": [
                              "_id"
                            ]
                          },
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "whatsapp": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "status",
                    "transaction",
                    "transactionReq"
                  ],
                  "additionalProperties": true
                }
              },
              "hasMoreEntries": {
                "type": "boolean"
              }
            },
            "required": [
              "status",
              "timestamp",
              "widgetAttempt",
              "transaction",
              "transactionReq",
              "publicMetadata",
              "privateMetadata"
            ],
            "additionalProperties": true
          },
          "waited": {
            "type": "object",
            "properties": {
              "outcome": {
                "const": "verified"
              },
              "polls": {
                "type": "integer"
              },
              "elapsedSeconds": {
                "type": "number"
              }
            },
            "required": [
              "outcome",
              "polls",
              "elapsedSeconds"
            ],
            "additionalProperties": true
          },
          "attempt": {
            "type": "object",
            "properties": {
              "attemptId": {
                "type": "string"
              },
              "iframeUrl": {
                "type": "string",
                "format": "uri"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "attemptId",
              "iframeUrl",
              "expiresAt"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "status",
          "data"
        ],
        "additionalProperties": true
      },
      {
        "type": "object",
        "properties": {
          "status": {
            "const": "success"
          },
          "data": {
            "type": "object",
            "properties": {
              "transactions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "transactionID": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryable": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "certainty": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "transactionID"
                  ],
                  "additionalProperties": true
                }
              },
              "attempts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "attemptId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "retryable": {
                      "type": "boolean"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "certainty": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "attemptId"
                  ],
                  "additionalProperties": true
                }
              }
            },
            "required": [
              "transactions",
              "attempts"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "status",
          "data"
        ],
        "additionalProperties": true
      }
    ]
  },
  "variants": [
    {
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "httpStatus": {
            "type": [
              "integer",
              "null"
            ]
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          },
          "hint": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      },
      "title": "API refusal",
      "when": "A non-success HTTP response; CLI reports a structured error on stderr/stdout according to output mode and preserves backend code/message when present.",
      "notes": []
    },
    {
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "status": {
            "const": "success"
          },
          "data": {
            "type": "object",
            "properties": {
              "transactions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "transactionID": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "transactionID"
                  ],
                  "additionalProperties": true
                }
              },
              "attempts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "attemptId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "attemptId"
                  ],
                  "additionalProperties": true
                }
              }
            },
            "required": [
              "transactions",
              "attempts"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "status",
          "data"
        ],
        "additionalProperties": true
      },
      "title": "batch lookup",
      "when": "--transaction-ids and/or --attempt-ids selects the /status/batch endpoint; response data has separate transactions and attempts arrays, with per-item status/error fields.",
      "notes": []
    }
  ],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": "Projection is not redaction; selecting sensitive paths can print Secrets or live OTP values. Use the command secret sink where supported and keep output private."
  }
}

json

[
  {
    "title": "Synthetic successful response",
    "value": {
      "status": "success",
      "data": {
        "mainTransaction": {
          "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
          "status": "Pending",
          "verificationAddress": {
            "phoneNumber": "+201234567890"
          },
          "expirationDate": "2026-10-29T12:05:00.000Z"
        },
        "transactionReq": {
          "_id": "65a1b2c3d4e5f67890123456",
          "status": "Pending",
          "verified": false
        }
      }
    }
  },
  {
    "title": "Synthetic widget-attempt status response",
    "value": {
      "status": "success",
      "data": {
        "status": "success",
        "timestamp": "2026-10-29T12:00:03.000Z",
        "widgetAttempt": {
          "attemptId": "att_synthetic_01",
          "widgetId": "wid_synthetic_01",
          "userId": "65a1b2c3d4e5f67890123458",
          "status": "verified",
          "isTest": true,
          "verificationAddress": {
            "phoneNumber": "+201234567890",
            "email": null
          },
          "otpConfig": {
            "digits": 6,
            "resendCount": 0
          },
          "publicMetadata": {
            "fixture": "synthetic"
          },
          "createdAt": "2026-10-29T12:00:00.000Z",
          "expiresAt": "2026-10-29T12:05:00.000Z",
          "captchaVerifiedAt": "2026-10-29T12:00:00.000Z",
          "otpRequestedAt": "2026-10-29T12:00:00.000Z",
          "completedAt": "2026-10-29T12:00:03.000Z"
        },
        "transaction": {
          "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
          "status": "Successful",
          "verificationAddress": {
            "phoneNumber": "+201234567890"
          },
          "expirationDate": "2026-10-29T12:05:00.000Z",
          "creationDate": "2026-10-29T12:00:00.000Z"
        },
        "transactionReq": {
          "_id": "65a1b2c3d4e5f67890123456",
          "status": "Successful",
          "verified": true,
          "billingAmount": 0.25,
          "billed": true,
          "verificationDate": "2026-10-29T12:00:03.000Z"
        },
        "publicMetadata": {
          "fixture": "synthetic"
        },
        "privateMetadata": {
          "ref": "synthetic"
        },
        "entries": [],
        "hasMoreEntries": false
      }
    }
  },
  {
    "title": "Synthetic batch response",
    "value": {
      "status": "success",
      "data": {
        "transactions": [
          {
            "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
            "status": "success",
            "data": {
              "mainTransaction": {
                "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
                "status": "Pending",
                "verificationAddress": {
                  "phoneNumber": "+201234567890"
                },
                "expirationDate": "2026-10-29T12:05:00.000Z"
              },
              "transactionReq": {
                "_id": "65a1b2c3d4e5f67890123456",
                "status": "Pending",
                "verified": false
              }
            }
          }
        ],
        "attempts": [
          {
            "attemptId": "att_synthetic_01",
            "status": "success",
            "data": {
              "status": "success",
              "timestamp": "2026-10-29T12:00:03.000Z",
              "widgetAttempt": {
                "attemptId": "att_synthetic_01",
                "widgetId": "wid_synthetic_01",
                "userId": "65a1b2c3d4e5f67890123458",
                "status": "success",
                "isTest": true,
                "verificationAddress": {
                  "phoneNumber": "+201234567890",
                  "email": null
                },
                "otpConfig": {
                  "digits": 6,
                  "resendCount": 0
                },
                "publicMetadata": {
                  "fixture": "synthetic"
                },
                "createdAt": "2026-10-29T12:00:00.000Z",
                "expiresAt": "2026-10-29T12:05:00.000Z",
                "captchaVerifiedAt": "2026-10-29T12:00:00.000Z",
                "otpRequestedAt": "2026-10-29T12:00:00.000Z",
                "completedAt": "2026-10-29T12:00:03.000Z"
              },
              "transaction": {
                "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
                "status": "Successful",
                "verificationAddress": {
                  "phoneNumber": "+201234567890"
                },
                "expirationDate": "2026-10-29T12:05:00.000Z",
                "creationDate": "2026-10-29T12:00:00.000Z"
              },
              "transactionReq": {
                "_id": "65a1b2c3d4e5f67890123456",
                "status": "Successful",
                "verified": true,
                "billingAmount": 0.25,
                "billed": true,
                "verificationDate": "2026-10-29T12:00:03.000Z"
              },
              "publicMetadata": {
                "fixture": "synthetic"
              },
              "privateMetadata": {
                "ref": "synthetic"
              }
            }
          }
        ]
      }
    }
  },
  {
    "title": "Synthetic transaction before an activation request exists",
    "value": {
      "status": "success",
      "data": {
        "mainTransaction": {
          "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
          "status": "Pending",
          "verificationAddress": {
            "phoneNumber": "+201234567890"
          },
          "expirationDate": "2026-10-29T12:05:00.000Z"
        },
        "transactionReq": null
      }
    }
  },
  {
    "title": "Synthetic V1.2 passkey replay with a synthesized request lacking _id",
    "value": {
      "status": "success",
      "data": {
        "mainTransaction": {
          "transactionID": "req_synthetic_v12",
          "status": "Pending",
          "verificationAddress": {
            "phoneNumber": "+201234567890"
          },
          "verificationMethod": "passkey",
          "pipelineID": "65a1b2c3d4e5f67890123457",
          "isTest": true
        },
        "transactionReq": {
          "status": "Pending",
          "verificationMethod": "passkey",
          "isTest": true
        }
      }
    }
  },
  {
    "title": "Synthetic widget attempt state: captcha_solved",
    "value": {
      "status": "success",
      "data": {
        "status": "pending",
        "timestamp": "2026-10-29T12:00:03.000Z",
        "widgetAttempt": {
          "attemptId": "att_synthetic_captcha_solved",
          "widgetId": "wid_synthetic_01",
          "userId": "65a1b2c3d4e5f67890123458",
          "isTest": true,
          "verificationAddress": {
            "phoneNumber": "+201234567890",
            "email": null
          },
          "otpConfig": {
            "digits": 6,
            "resendCount": 0
          },
          "publicMetadata": null,
          "createdAt": "2026-10-29T12:00:00.000Z",
          "expiresAt": "2026-10-29T12:05:00.000Z",
          "captchaVerifiedAt": "2026-10-29T12:00:01.000Z",
          "otpRequestedAt": null,
          "completedAt": null,
          "status": "captcha_solved"
        },
        "transaction": null,
        "transactionReq": null,
        "publicMetadata": null,
        "privateMetadata": null,
        "entries": [],
        "hasMoreEntries": false
      }
    }
  },
  {
    "title": "Synthetic widget attempt state: otp_requested",
    "value": {
      "status": "success",
      "data": {
        "status": "pending",
        "timestamp": "2026-10-29T12:00:03.000Z",
        "widgetAttempt": {
          "attemptId": "att_synthetic_otp_requested",
          "widgetId": "wid_synthetic_01",
          "userId": "65a1b2c3d4e5f67890123458",
          "isTest": true,
          "verificationAddress": {
            "phoneNumber": "+201234567890",
            "email": null
          },
          "otpConfig": {
            "digits": 6,
            "resendCount": 0
          },
          "publicMetadata": null,
          "createdAt": "2026-10-29T12:00:00.000Z",
          "expiresAt": "2026-10-29T12:05:00.000Z",
          "captchaVerifiedAt": "2026-10-29T12:00:01.000Z",
          "otpRequestedAt": "2026-10-29T12:00:02.000Z",
          "completedAt": null,
          "status": "otp_requested"
        },
        "transaction": null,
        "transactionReq": null,
        "publicMetadata": null,
        "privateMetadata": null,
        "entries": [],
        "hasMoreEntries": false
      }
    }
  },
  {
    "title": "Synthetic widget attempt state: failed",
    "value": {
      "status": "success",
      "data": {
        "status": "failed",
        "timestamp": "2026-10-29T12:00:03.000Z",
        "widgetAttempt": {
          "attemptId": "att_synthetic_failed",
          "widgetId": "wid_synthetic_01",
          "userId": "65a1b2c3d4e5f67890123458",
          "isTest": true,
          "verificationAddress": {
            "phoneNumber": "+201234567890",
            "email": null
          },
          "otpConfig": {
            "digits": 6,
            "resendCount": 0
          },
          "publicMetadata": null,
          "createdAt": "2026-10-29T12:00:00.000Z",
          "expiresAt": "2026-10-29T12:05:00.000Z",
          "captchaVerifiedAt": null,
          "otpRequestedAt": null,
          "completedAt": "2026-10-29T12:05:00.000Z",
          "status": "failed"
        },
        "transaction": null,
        "transactionReq": null,
        "publicMetadata": null,
        "privateMetadata": null,
        "entries": [],
        "hasMoreEntries": false
      }
    }
  },
  {
    "title": "Synthetic widget attempt state: expired",
    "value": {
      "status": "success",
      "data": {
        "status": "failed",
        "timestamp": "2026-10-29T12:00:03.000Z",
        "widgetAttempt": {
          "attemptId": "att_synthetic_expired",
          "widgetId": "wid_synthetic_01",
          "userId": "65a1b2c3d4e5f67890123458",
          "isTest": true,
          "verificationAddress": {
            "phoneNumber": "+201234567890",
            "email": null
          },
          "otpConfig": {
            "digits": 6,
            "resendCount": 0
          },
          "publicMetadata": null,
          "createdAt": "2026-10-29T12:00:00.000Z",
          "expiresAt": "2026-10-29T12:05:00.000Z",
          "captchaVerifiedAt": null,
          "otpRequestedAt": null,
          "completedAt": "2026-10-29T12:05:00.000Z",
          "status": "expired"
        },
        "transaction": null,
        "transactionReq": null,
        "publicMetadata": null,
        "privateMetadata": null,
        "entries": [],
        "hasMoreEntries": false
      }
    }
  },
  {
    "title": "Synthetic batch with per-ID scope refusal",
    "value": {
      "status": "success",
      "data": {
        "transactions": [
          {
            "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
            "status": "success",
            "data": {
              "mainTransaction": {
                "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
                "status": "Pending"
              },
              "transactionReq": null
            }
          },
          {
            "transactionID": "tx_out_of_scope_synthetic",
            "status": "error",
            "code": "API_KEY_SCOPE_DENIED",
            "message": "This API key is not authorized for the requested pipeline"
          }
        ],
        "attempts": []
      }
    }
  }
]

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

transactions list

Review account transaction history for reconciliation, support investigation, or customer reporting.

When to use

For a customer login account, filter by date/status/pipeline/phone and page through history. Do not run from an Akedly staff/admin account: server scope can return all accounts.

How it works

Login-authenticated GET uses the caller owner ID and server filters; --all fetches pages, deduplicates repeated _ids, and keeps first-page envelope with final pagination.

Prerequisites

A stored CLI Login for this region with the command permission.

Expected outcome

Returns transaction rows with pagination and appliedFilters. Rows can contain phone numbers and live OTP fields; keep output private.

Next steps

For current lifecycle state, use transactions status with a non-utility transactionID.

Usage

akedly transactions list

Inspect this command offline before preparing an operation:

akedly describe "transactions list" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--page`	integer	1 to unbounded	Command-specific option; see the full command details below. Query parameter: page.
`--limit`	integer	1 to 100	Command-specific option; see the full command details below. Query parameter: limit.
`--all`	boolean switch	—	Command-specific option; see the full command details below.
`--status`	enum	Pending \| Successful \| Failed	Command-specific option; see the full command details below. Query parameter: status.
`--phone-number`	text	—	Command-specific option; see the full command details below. Query parameter: phoneNumber.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Query parameter: pipelineID.
`--billing-mode`	enum	PPM \| PPS	Command-specific option; see the full command details below. Query parameter: billingMode.
`--exclude-utility`	boolean switch	—	Command-specific option; see the full command details below. Query parameter: excludeUtility.
`--sort-by`	enum	creationDate \| status \| transactionID	Command-specific option; see the full command details below. Query parameter: sortBy.
`--sort-order`	enum	asc \| desc	Command-specific option; see the full command details below. Query parameter: sortOrder.
`--start-date`	text	—	Command-specific option; see the full command details below. Query parameter: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Query parameter: eDate.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: verifications:read.

Server request: GET /transactions/user/:userID/paginated.

Owner parameters resolved from the CLI Login: userID.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

List transaction history for the caller account with full returned rows, including personal data, phone numbers and live OTPs; handle output privately. Uses the login owner id; no targetUserID override. On an Akedly staff (admin) account the server ignores the owner scope and returns unsanitised history for every account; do not run it there. Utility transactions are included by default; --exclude-utility omits them. --page defaults to 1 and --limit to 20, with a maximum of 100. Under --all, an omitted --limit defaults to 100 on every page. --phone-number is a case-insensitive substring filter. --start-date and --end-date pass through as server-local inclusive day bounds, without a date-range cap; invalid dates can fail on the server. For --all paging, see the shared Pagination rules in akedly agent-guide. --fields does not project inside row arrays. To check one row's current status, pass its transactionID to transactions status --transaction-id <transactionID>; that command uses an API key, not the CLI Login, and does not cover utility rows. There is no authenticated single-history-get command. A sort with tied values (status, or equal creationDate values) can also skip or repeat rows between pages; --all removes repeats but cannot recover skipped rows. Prefer the default creationDate sort with --all; status and transactionID sorts can be slow on large histories.

Pagination rules.

Worked examples

Synthetic offline fixture

Review account transaction history for reconciliation, support investigation, or customer reporting.

akedly transactions list --status Successful --all

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "message": "Transactions fetched successfully",
  "data": {
    "transactions": [
      {
        "_id": "65a1b2c3d4e5f67890123456",
        "transactionID": "9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f9f",
        "status": "Pending",
        "verificationAddress": {
          "phoneNumber": "+201234567890"
        },
        "expirationDate": "2026-10-29T12:05:00.000Z",
        "creationDate": "2026-10-29T12:00:00.000Z",
        "pipeline": {
          "_id": "65a1b2c3d4e5f67890123457",
          "name": "Example OTP pipeline",
          "channel": "sms"
        },
        "channels": [
          "sms"
        ]
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": null,
      "totalCount": null,
      "limit": 20,
      "hasNextPage": null,
      "hasPreviousPage": false
    },
    "appliedFilters": {
      "targetUserID": null,
      "status": null,
      "dateRange": null,
      "phoneNumber": null,
      "pipelineID": null,
      "billingMode": null
    }
  }
}

This worked response is illustrative only and was not executed against an account.

Additional command forms

akedly transactions list --page 1 --limit 20

akedly transactions list --status Successful --all

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "page",
      "schema": {
        "type": "string",
        "pattern": "^(?:\\+?0*(?:[1-9]\\d*)(?:\\.0+)?)$"
      },
      "required": false,
      "wire": [
        {
          "path": "page",
          "transform": "identity",
          "role": "query",
          "input": "page",
          "contributors": [
            "page"
          ]
        }
      ],
      "validation": {
        "syntax": "Decimal integer token.",
        "minimum": 1,
        "parsedValueSchema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    {
      "name": "limit",
      "schema": {
        "type": "string",
        "pattern": "^(?:\\+?0*(?:[1-9]|(?:1[0-9]|[2-8]\\d{1}|9[0-9])|100)(?:\\.0+)?)$"
      },
      "required": false,
      "wire": [
        {
          "path": "limit",
          "transform": "identity",
          "role": "query",
          "input": "limit",
          "contributors": [
            "limit"
          ]
        }
      ],
      "validation": {
        "syntax": "Decimal integer token.",
        "minimum": 1,
        "maximum": 100,
        "parsedValueSchema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        }
      }
    },
    {
      "name": "all",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "all",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "all",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "all",
          "contributors": [
            "all"
          ]
        }
      ]
    },
    {
      "name": "status",
      "schema": {
        "type": "string",
        "enum": [
          "Pending",
          "Successful",
          "Failed"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "status",
          "transform": "identity",
          "role": "query",
          "input": "status",
          "contributors": [
            "status"
          ]
        }
      ]
    },
    {
      "name": "phone-number",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "phoneNumber",
          "transform": "identity",
          "role": "query",
          "input": "phone-number",
          "contributors": [
            "phone-number"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "query",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "billing-mode",
      "schema": {
        "type": "string",
        "enum": [
          "PPM",
          "PPS"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "billingMode",
          "transform": "identity",
          "role": "query",
          "input": "billing-mode",
          "contributors": [
            "billing-mode"
          ]
        }
      ]
    },
    {
      "name": "exclude-utility",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "wire": [
        {
          "path": "excludeUtility",
          "transform": "identity",
          "role": "query",
          "input": "exclude-utility",
          "contributors": [
            "exclude-utility"
          ]
        }
      ]
    },
    {
      "name": "sort-by",
      "schema": {
        "type": "string",
        "enum": [
          "creationDate",
          "status",
          "transactionID"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "sortBy",
          "transform": "identity",
          "role": "query",
          "input": "sort-by",
          "contributors": [
            "sort-by"
          ]
        }
      ]
    },
    {
      "name": "sort-order",
      "schema": {
        "type": "string",
        "enum": [
          "asc",
          "desc"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "sortOrder",
          "transform": "identity",
          "role": "query",
          "input": "sort-order",
          "contributors": [
            "sort-order"
          ]
        }
      ]
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "query",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "query",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "GET",
    "route": "/transactions/user/:userID/paginated",
    "query": {
      "page": [
        {
          "path": "page",
          "transform": "identity",
          "role": "query",
          "input": "page",
          "contributors": [
            "page"
          ]
        }
      ],
      "limit": [
        {
          "path": "limit",
          "transform": "identity",
          "role": "query",
          "input": "limit",
          "contributors": [
            "limit"
          ]
        }
      ],
      "status": [
        {
          "path": "status",
          "transform": "identity",
          "role": "query",
          "input": "status",
          "contributors": [
            "status"
          ]
        }
      ],
      "phone-number": [
        {
          "path": "phoneNumber",
          "transform": "identity",
          "role": "query",
          "input": "phone-number",
          "contributors": [
            "phone-number"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "query",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "billing-mode": [
        {
          "path": "billingMode",
          "transform": "identity",
          "role": "query",
          "input": "billing-mode",
          "contributors": [
            "billing-mode"
          ]
        }
      ],
      "exclude-utility": [
        {
          "path": "excludeUtility",
          "transform": "identity",
          "role": "query",
          "input": "exclude-utility",
          "contributors": [
            "exclude-utility"
          ]
        }
      ],
      "sort-by": [
        {
          "path": "sortBy",
          "transform": "identity",
          "role": "query",
          "input": "sort-by",
          "contributors": [
            "sort-by"
          ]
        }
      ],
      "sort-order": [
        {
          "path": "sortOrder",
          "transform": "identity",
          "role": "query",
          "input": "sort-order",
          "contributors": [
            "sort-order"
          ]
        }
      ],
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "query",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "query",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    "body": {},
    "ownerParams": [
      "userID"
    ]
  }
}

Response contract

Successful response example is synthetic and demonstrates observed field names/types; server-supplied extension fields are preserved.

Responses can contain personal data and, on some transaction paths, live OTP-related values. Treat actual output as secret; examples contain only synthetic fixture values.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "message": {
        "type": "string"
      },
      "data": {
        "type": "object",
        "properties": {
          "transactions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string"
                },
                "transactionID": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "verificationAddress": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "phoneNumber": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "expirationDate": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "creationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "updateDate": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "pipeline": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "channel": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "additionalProperties": true
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "billingAmount": {
                  "type": "number"
                },
                "billed": {
                  "type": "boolean"
                },
                "channels": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "otp": {
                  "type": "string"
                },
                "product": {
                  "type": "string"
                },
                "company": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": true
                }
              },
              "required": [
                "_id",
                "status"
              ],
              "additionalProperties": true
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "currentPage": {
                "type": "integer"
              },
              "totalPages": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "totalCount": {
                "anyOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "limit": {
                "type": "integer"
              },
              "hasNextPage": {
                "anyOf": [
                  {
                    "type": "boolean"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "hasPreviousPage": {
                "type": "boolean"
              }
            },
            "required": [
              "currentPage",
              "limit",
              "hasPreviousPage"
            ],
            "additionalProperties": true
          },
          "appliedFilters": {
            "type": "object",
            "properties": {
              "targetUserID": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "status": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "dateRange": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "sDate": {
                        "type": "string"
                      },
                      "eDate": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "phoneNumber": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "pipelineID": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "billingMode": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "additionalProperties": true
          }
        },
        "required": [
          "transactions",
          "pagination",
          "appliedFilters"
        ],
        "additionalProperties": true
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [
    {
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "httpStatus": {
            "type": [
              "integer",
              "null"
            ]
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          },
          "hint": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": true
      },
      "title": "API refusal",
      "when": "A non-success HTTP response; CLI reports a structured error on stderr/stdout according to output mode and preserves backend code/message when present.",
      "notes": []
    }
  ],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": "Projection is not redaction; selecting sensitive paths can print Secrets or live OTP values. Use the command secret sink where supported and keep output private."
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics current-rate

Read current national, international and TOTP rates using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need national international and totp current rates in egp and usd, plus legacy compatibility rates to monitor product usage, service outcomes or account spend.

How it works

The CLI calls the current-rate endpoint with the authenticated owner identity; this endpoint does not accept a date window or account/pipeline scope.
Rates include national, international and TOTP amounts; USD fields are strings calculated by the backend at the documented conversion constant, while EGP values are numbers.
Exact endpoint behavior and scope caveats: Read national, international and TOTP rates for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing national international and totp current rates in egp and usd, plus legacy compatibility rates.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics current-rate

Inspect this command offline before preparing an operation:

akedly describe "analytics current-rate" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_current_rates:read.

Server request: POST /analytics/getCurrentRate.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read national, international and TOTP rates for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override.

Worked examples

Example analytics current-rate

national international and TOTP current rates in EGP and USD, plus legacy compatibility rates for the login owner's account.

akedly analytics current-rate

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "rates": {
      "national": {
        "egp": 1,
        "usd": "0.02"
      },
      "international": {
        "egp": 10,
        "usd": "0.20"
      },
      "totp": {
        "egp": 0.25,
        "usd": "0.01"
      }
    },
    "rateInEGP": "1.00",
    "rateInUSD": "0.02"
  }
}

Additional command forms

akedly analytics current-rate --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getCurrentRate",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "rates": {
            "type": "object",
            "properties": {
              "national": {
                "type": "object",
                "properties": {
                  "egp": {
                    "type": "number"
                  },
                  "usd": {
                    "type": "string"
                  }
                },
                "required": [
                  "egp",
                  "usd"
                ],
                "additionalProperties": true
              },
              "international": {
                "type": "object",
                "properties": {
                  "egp": {
                    "type": "number"
                  },
                  "usd": {
                    "type": "string"
                  }
                },
                "required": [
                  "egp",
                  "usd"
                ],
                "additionalProperties": true
              },
              "totp": {
                "type": "object",
                "properties": {
                  "egp": {
                    "type": "number"
                  },
                  "usd": {
                    "type": "string"
                  }
                },
                "required": [
                  "egp",
                  "usd"
                ],
                "additionalProperties": true
              }
            },
            "required": [
              "national",
              "international",
              "totp"
            ],
            "additionalProperties": true
          },
          "rateInEGP": {
            "type": "string"
          },
          "rateInUSD": {
            "type": "string"
          }
        },
        "required": [
          "rates",
          "rateInEGP",
          "rateInUSD"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics total-transactions

Read OTP, passkey and TOTP verification totals using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need count of otp verification transactions (with excluded passkey/totp counters) to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getTotalMainTransactions and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Unscoped totals include OTP plus verified passkey and TOTP. Under pipeline/widget scope TOTP cannot be attributed and is excluded (totpExcluded=true); a widget scope also excludes V1.2 passkeys (v12Excluded=true). False means the respective exclusion does not apply.
Unscoped counts include OTP plus verified passkey and TOTP. Under pipeline/widget scope TOTP cannot be attributed and is excluded (totpExcluded=true); widget scope also excludes V1.2 passkeys (v12Excluded=true). The booleans are false when the respective exclusion does not apply.
Exact endpoint behavior and scope caveats: Count verification transactions for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing count of otp verification transactions (with excluded passkey/totp counters).

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics total-transactions

Inspect this command offline before preparing an operation:

akedly describe "analytics total-transactions" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_total_main_tx:read.

Server request: POST /analytics/getTotalMainTransactions.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Count verification transactions for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics total-transactions

count of OTP verification transactions (with excluded passkey/TOTP counters) for the login owner's account.

akedly analytics total-transactions --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "transactionsNumber": 42,
    "totpExcluded": false,
    "v12Excluded": false
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics total-transactions --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getTotalMainTransactions",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. Under no pipeline/widget filter, verified passkey and TOTP counts are included. If a selected scope cannot attribute one of those methods, the corresponding boolean is true.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics total-requests

Read verification request totals using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need count of verification requests to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getTotalTransactionRequests and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Exact endpoint behavior and scope caveats: Count verification requests for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing count of verification requests.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics total-requests

Inspect this command offline before preparing an operation:

akedly describe "analytics total-requests" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_total_tx_reqs:read.

Server request: POST /analytics/getTotalTransactionRequests.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Count verification requests for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics total-requests

count of verification requests for the login owner's account.

akedly analytics total-requests --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "transactionsNumber": 51
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics total-requests --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getTotalTransactionRequests",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics successful

Read successful verification totals using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need count of successful otp, passkey and totp verifications to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getTotalSuccessfulTransactions and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Unscoped counts include successful OTP, verified passkey and verified TOTP. Scope-exclusion booleans identify un-attributable TOTP or V1.2 passkeys; they are false when those omissions do not apply.
Unscoped counts include OTP plus verified passkey and TOTP. Under pipeline/widget scope TOTP cannot be attributed and is excluded (totpExcluded=true); widget scope also excludes V1.2 passkeys (v12Excluded=true). The booleans are false when the respective exclusion does not apply.
Exact endpoint behavior and scope caveats: Count successful verifications (OTP, passkey and TOTP) for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing count of successful otp, passkey and totp verifications.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics successful

Inspect this command offline before preparing an operation:

akedly describe "analytics successful" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_successful:read.

Server request: POST /analytics/getTotalSuccessfulTransactions.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Count successful verifications (OTP, passkey and TOTP) for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics successful

count of successful OTP, passkey and TOTP verifications for the login owner's account.

akedly analytics successful --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "transactionsNumber": 37,
    "totpExcluded": false,
    "v12Excluded": false
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics successful --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getTotalSuccessfulTransactions",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics failed

Read failed OTP counts and records using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need count and customer-sanitized failed otp transaction records to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getTotalFailedTransactions and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. Returned transaction lists may contain personal data and live OTPs; keep output private. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. The list covers every match in the window; for just the count use --fields data.transactionsNumber.
Exact endpoint behavior and scope caveats: Count and list failed OTP verifications for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. Returned transaction lists may contain personal data and live OTPs; keep output private. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. The list covers every match in the window; for just the count use --fields data.transactionsNumber.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing count and customer-sanitized failed otp transaction records.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics failed

Inspect this command offline before preparing an operation:

akedly describe "analytics failed" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_failed:read.

Server request: POST /analytics/getTotalFailedTransactions.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Count and list failed OTP verifications for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. Returned transaction lists may contain personal data and live OTPs; keep output private. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. The list covers every match in the window; for just the count use --fields data.transactionsNumber.

Worked examples

Example analytics failed

count and customer-sanitized failed OTP transaction records for the login owner's account.

akedly analytics failed --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "transactionsNumber": 1,
    "transactions": [
      {
        "transactionID": "tx_synthetic_1",
        "status": "Failed",
        "verificationAddress": "+201234567890",
        "resolvedChannel": "sms",
        "isTest": true,
        "creationDate": "2026-10-04T10:00:00Z"
      }
    ]
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics failed --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getTotalFailedTransactions",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "transactionsNumber": {
            "type": "integer"
          },
          "transactions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "transactionID": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "verificationAddress": {
                  "type": "string"
                },
                "resolvedChannel": {
                  "type": "string"
                },
                "channels": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {},
                    "required": [],
                    "additionalProperties": true
                  }
                },
                "isTest": {
                  "type": "boolean"
                },
                "creationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "expirationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "updateDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "verificationMethod": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "transactionsNumber",
          "transactions"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": "Projection is not redaction; selecting sensitive paths can print Secrets or live OTP values. Use the command secret sink where supported and keep output private."
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics auth-ratio

Read authentication success ratio and transaction records using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need successful-versus-failed authentication ratio and sanitized transaction lists to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getAuthenticationRatio and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. Returned transaction lists may contain personal data and live OTPs; keep output private. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. For just the ratio use --fields data.authenticationRatio.
Exact endpoint behavior and scope caveats: Read the authentication ratio and successful/failed transaction lists for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. Returned transaction lists may contain personal data and live OTPs; keep output private. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. For just the ratio use --fields data.authenticationRatio.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing successful-versus-failed authentication ratio and sanitized transaction lists.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics auth-ratio

Inspect this command offline before preparing an operation:

akedly describe "analytics auth-ratio" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_auth_ratio:read.

Server request: POST /analytics/getAuthenticationRatio.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Sensitive output: live-otp. Responses may contain live OTP fields; keep them private.

Full command details

Read the authentication ratio and successful/failed transaction lists for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. Returned transaction lists may contain personal data and live OTPs; keep output private. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. For just the ratio use --fields data.authenticationRatio.

Worked examples

Example analytics auth-ratio

successful-versus-failed authentication ratio and sanitized transaction lists for the login owner's account.

akedly analytics auth-ratio --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "authenticationRatio": 94.87,
    "successfulTransactions": [
      {
        "transactionID": "tx_synthetic_1",
        "status": "Successful",
        "verificationAddress": "+201234567890",
        "resolvedChannel": "sms",
        "isTest": true,
        "creationDate": "2026-10-04T10:00:00Z"
      }
    ],
    "failedTransactions": []
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics auth-ratio --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getAuthenticationRatio",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "authenticationRatio": {
            "type": "number"
          },
          "successfulTransactions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "transactionID": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "verificationAddress": {
                  "type": "string"
                },
                "resolvedChannel": {
                  "type": "string"
                },
                "channels": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {},
                    "required": [],
                    "additionalProperties": true
                  }
                },
                "isTest": {
                  "type": "boolean"
                },
                "creationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "expirationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "updateDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "verificationMethod": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": true
            }
          },
          "failedTransactions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "transactionID": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "verificationAddress": {
                  "type": "string"
                },
                "resolvedChannel": {
                  "type": "string"
                },
                "channels": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {},
                    "required": [],
                    "additionalProperties": true
                  }
                },
                "isTest": {
                  "type": "boolean"
                },
                "creationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "expirationDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "updateDate": {
                  "type": "string",
                  "format": "date-time"
                },
                "verificationMethod": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "authenticationRatio",
          "successfulTransactions",
          "failedTransactions"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": "Projection is not redaction; selecting sensitive paths can print Secrets or live OTP values. Use the command secret sink where supported and keep output private."
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics billing-consumption

Read usage bills and amount summaries using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need usage bills and billed amount breakdown to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getBillingConsumption and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. This customer route keeps owner scope even for an admin account; it does not apply the my-costs granular-pricing gate. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Exact endpoint behavior and scope caveats: Read usage bills and their amount breakdown for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. This customer route keeps owner scope even for an admin account; it does not apply the my-costs granular-pricing gate. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing usage bills and billed amount breakdown.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics billing-consumption

Inspect this command offline before preparing an operation:

akedly describe "analytics billing-consumption" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: billing:read.

Server request: POST /analytics/getBillingConsumption.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read usage bills and their amount breakdown for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. This customer route keeps owner scope even for an admin account; it does not apply the my-costs granular-pricing gate. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics billing-consumption

usage bills and billed amount breakdown for the login owner's account.

akedly analytics billing-consumption --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "billsNumber": 1,
    "bills": [
      {
        "_id": "bill_synthetic_1",
        "amount": 1,
        "transactionType": "National OTP",
        "type": "Usage",
        "creationDate": "2026-10-04T10:00:00Z"
      }
    ],
    "summary": {
      "totalAmount": 1,
      "averageAmount": 1,
      "breakdown": {
        "national": {
          "count": 1,
          "totalAmount": 1,
          "averageAmount": 1
        },
        "international": {
          "count": 0,
          "totalAmount": 0,
          "averageAmount": 0
        },
        "totp": {
          "count": 0,
          "totalAmount": 0,
          "averageAmount": 0
        },
        "passkey": {
          "count": 0,
          "totalAmount": 0,
          "averageAmount": 0
        },
        "optin": {
          "count": 0,
          "totalAmount": 0,
          "averageAmount": 0
        },
        "default": {
          "count": 0,
          "totalAmount": 0,
          "averageAmount": 0
        },
        "unknown": {
          "count": 0,
          "totalAmount": 0,
          "averageAmount": 0
        }
      }
    }
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics billing-consumption --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getBillingConsumption",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. Numeric monetary amounts and cost/rate totals in this endpoint are EGP. `analytics current-rate` separately returns USD compatibility figures as two-decimal strings. Each `bills[]` item is a customer-safe projection; it deliberately omits currency/provider pricing internals, while summary amounts are the analytics bill amounts.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "billsNumber": {
            "type": "integer"
          },
          "bills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                },
                "transactionType": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "creationDate": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [],
              "additionalProperties": true
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "totalAmount": {
                "type": "number"
              },
              "averageAmount": {
                "type": "number"
              },
              "breakdown": {
                "type": "object",
                "properties": {
                  "national": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  },
                  "international": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  },
                  "totp": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  },
                  "passkey": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  },
                  "optin": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  },
                  "default": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  },
                  "unknown": {
                    "type": "object",
                    "properties": {
                      "count": {
                        "type": "integer"
                      },
                      "totalAmount": {
                        "type": "number"
                      },
                      "averageAmount": {
                        "type": "number"
                      }
                    },
                    "required": [
                      "count",
                      "totalAmount",
                      "averageAmount"
                    ],
                    "additionalProperties": true
                  }
                },
                "required": [
                  "national",
                  "international",
                  "totp",
                  "passkey",
                  "optin",
                  "default",
                  "unknown"
                ],
                "additionalProperties": true
              }
            },
            "required": [
              "totalAmount",
              "averageAmount",
              "breakdown"
            ],
            "additionalProperties": true
          },
          "scopeDisclosure": {
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": true
          }
        },
        "required": [
          "billsNumber",
          "bills",
          "summary"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics savings

Read verification-method savings and rate baselines using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need estimated savings and method breakdown to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getSavings and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Unscoped metrics include available TOTP/passkey data. Under a selected scope the response flags or scoped source breakdown indicate methods that cannot be attributed rather than implying a zero count.
Exact endpoint behavior and scope caveats: Read total savings and the verification-method breakdown for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing estimated savings and method breakdown.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics savings

Inspect this command offline before preparing an operation:

akedly describe "analytics savings" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_savings:read.

Server request: POST /analytics/getSavings.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read total savings and the verification-method breakdown for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics savings

estimated savings and method breakdown for the login owner's account.

akedly analytics savings --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "totalSavings": 3,
    "totpExcluded": false,
    "v12Excluded": false,
    "breakdown": {
      "successful": {
        "nationalSavings": 1,
        "internationalSavings": 1,
        "totpSavings": 0,
        "passkeySavings": 1,
        "nationalCount": 1,
        "internationalCount": 1,
        "totpCount": 0,
        "passkeyCount": 1
      },
      "failed": {
        "nationalSavings": 0,
        "internationalSavings": 0,
        "totpSavings": 0,
        "nationalCount": 0,
        "internationalCount": 0,
        "totpCount": 0
      }
    },
    "currentRates": {
      "national": 1,
      "international": 10,
      "totp": 0.25
    },
    "nationalSavings": 0,
    "internationalSavings": 0,
    "nationalCost": 1,
    "internationalCost": 1
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics savings --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getSavings",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. Unscoped savings include TOTP/passkey contributions where available; true exclusion flags disclose when pipeline/widget scope prevents attribution. Numeric monetary amounts and cost/rate totals in this endpoint are EGP. `analytics current-rate` separately returns USD compatibility figures as two-decimal strings.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "totalSavings": {
            "type": "number"
          },
          "totpExcluded": {
            "type": "boolean"
          },
          "v12Excluded": {
            "type": "boolean"
          },
          "breakdown": {
            "type": "object",
            "properties": {
              "successful": {
                "type": "object",
                "properties": {
                  "nationalSavings": {
                    "type": "number"
                  },
                  "internationalSavings": {
                    "type": "number"
                  },
                  "totpSavings": {
                    "type": "number"
                  },
                  "passkeySavings": {
                    "type": "number"
                  },
                  "nationalCount": {
                    "type": "integer"
                  },
                  "internationalCount": {
                    "type": "integer"
                  },
                  "totpCount": {
                    "type": "integer"
                  },
                  "passkeyCount": {
                    "type": "integer"
                  }
                },
                "required": [],
                "additionalProperties": true
              },
              "failed": {
                "type": "object",
                "properties": {
                  "nationalSavings": {
                    "type": "number"
                  },
                  "internationalSavings": {
                    "type": "number"
                  },
                  "totpSavings": {
                    "type": "number"
                  },
                  "nationalCount": {
                    "type": "integer"
                  },
                  "internationalCount": {
                    "type": "integer"
                  },
                  "totpCount": {
                    "type": "integer"
                  }
                },
                "required": [],
                "additionalProperties": true
              }
            },
            "required": [
              "successful",
              "failed"
            ],
            "additionalProperties": true
          },
          "currentRates": {
            "type": "object",
            "properties": {
              "national": {
                "type": "number"
              },
              "international": {
                "type": "number"
              },
              "totp": {
                "type": "number"
              }
            },
            "required": [
              "national",
              "international",
              "totp"
            ],
            "additionalProperties": true
          },
          "nationalSavings": {
            "type": "number"
          },
          "internationalSavings": {
            "type": "number"
          },
          "nationalCost": {
            "type": "number"
          },
          "internationalCost": {
            "type": "number"
          }
        },
        "required": [
          "totalSavings",
          "totpExcluded",
          "v12Excluded",
          "breakdown",
          "currentRates",
          "nationalSavings",
          "internationalSavings",
          "nationalCost",
          "internationalCost"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics savings-by-day

When to use

Use this when you need savings in daily, weekly or monthly buckets and rate baselines to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getSavingsByDay and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Unscoped metrics include available TOTP/passkey data. Under a selected scope the response flags or scoped source breakdown indicate methods that cannot be attributed rather than implying a zero count.
Exact endpoint behavior and scope caveats: Read savings by time bucket and rate baselines for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing savings in daily, weekly or monthly buckets and rate baselines.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics savings-by-day

Inspect this command offline before preparing an operation:

akedly describe "analytics savings-by-day" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--interval`	enum	daily \| weekly \| monthly	Command-specific option; see the full command details below. Manifest body field: interval.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_savings:read.

Server request: POST /analytics/getSavingsByDay.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read savings by time bucket and rate baselines for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics savings-by-day

savings in daily, weekly or monthly buckets and rate baselines for the login owner's account.

akedly analytics savings-by-day --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "savingsData": [
      {
        "date": "2026-10-04",
        "totalSavings": 1,
        "breakdown": {
          "successful": {
            "national": {
              "count": 1,
              "savings": 1,
              "cost": 0,
              "rate": 1
            },
            "international": {
              "count": 0,
              "savings": 0,
              "cost": 0,
              "rate": 10
            },
            "totp": {
              "count": 0,
              "savings": 0,
              "cost": 0,
              "rate": 0.25
            },
            "passkey": {
              "count": 0,
              "savings": 0,
              "cost": 0
            }
          },
          "failed": {
            "national": {
              "count": 0,
              "savings": 0,
              "baselineRate": 1
            },
            "international": {
              "count": 0,
              "savings": 0,
              "baselineRate": 33
            },
            "totp": {
              "count": 0,
              "savings": 0,
              "baselineRate": 1
            }
          }
        },
        "totalCost": 0,
        "totalTransactions": 1
      }
    ],
    "currentRates": {
      "national": 1,
      "international": 10,
      "totp": 0.25
    },
    "baselineRates": {
      "national": 1,
      "international": 33,
      "totp": 1
    },
    "totpExcluded": false,
    "v12Excluded": false
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics savings-by-day --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "interval",
      "schema": {
        "type": "string",
        "enum": [
          "daily",
          "weekly",
          "monthly"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "interval",
          "transform": "identity",
          "role": "body",
          "input": "interval",
          "contributors": [
            "interval"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getSavingsByDay",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ],
      "interval": [
        {
          "path": "interval",
          "transform": "identity",
          "role": "body",
          "input": "interval",
          "contributors": [
            "interval"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. Scoped savings rows can omit un-attributable TOTP or V1.2 methods; the booleans disclose these scoped exclusions. Numeric monetary amounts and cost/rate totals in this endpoint are EGP. `analytics current-rate` separately returns USD compatibility figures as two-decimal strings.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "savingsData": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "totalSavings": {
                  "type": "number"
                },
                "breakdown": {
                  "type": "object",
                  "properties": {
                    "successful": {
                      "type": "object",
                      "properties": {
                        "national": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "cost": {
                              "type": "number"
                            },
                            "rate": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        },
                        "international": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "cost": {
                              "type": "number"
                            },
                            "rate": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        },
                        "totp": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "cost": {
                              "type": "number"
                            },
                            "rate": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        },
                        "passkey": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "cost": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        }
                      },
                      "required": [],
                      "additionalProperties": true
                    },
                    "failed": {
                      "type": "object",
                      "properties": {
                        "national": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "baselineRate": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        },
                        "international": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "baselineRate": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        },
                        "totp": {
                          "type": "object",
                          "properties": {
                            "count": {
                              "type": "integer"
                            },
                            "savings": {
                              "type": "number"
                            },
                            "baselineRate": {
                              "type": "number"
                            }
                          },
                          "required": [],
                          "additionalProperties": true
                        }
                      },
                      "required": [],
                      "additionalProperties": true
                    }
                  },
                  "required": [],
                  "additionalProperties": true
                },
                "totalCost": {
                  "type": "number"
                },
                "totalTransactions": {
                  "type": "integer"
                }
              },
              "required": [
                "date",
                "totalSavings",
                "breakdown",
                "totalCost",
                "totalTransactions"
              ],
              "additionalProperties": true
            }
          },
          "currentRates": {
            "type": "object",
            "properties": {
              "national": {
                "type": "number"
              },
              "international": {
                "type": "number"
              },
              "totp": {
                "type": "number"
              }
            },
            "required": [
              "national",
              "international",
              "totp"
            ],
            "additionalProperties": true
          },
          "baselineRates": {
            "type": "object",
            "properties": {
              "national": {
                "type": "number"
              },
              "international": {
                "type": "number"
              },
              "totp": {
                "type": "number"
              }
            },
            "required": [
              "national",
              "international",
              "totp"
            ],
            "additionalProperties": true
          },
          "totpExcluded": {
            "type": "boolean"
          },
          "v12Excluded": {
            "type": "boolean"
          }
        },
        "required": [
          "savingsData",
          "currentRates",
          "baselineRates",
          "totpExcluded",
          "v12Excluded"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics transactions-graph

Read verification counts and outcomes over time using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need verification counts and outcomes by time bucket to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/graphTotalMainTransactions and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Unscoped metrics include available TOTP/passkey data. Under a selected scope the response flags or scoped source breakdown indicate methods that cannot be attributed rather than implying a zero count.
Exact endpoint behavior and scope caveats: Read verification counts and outcomes by time bucket for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing verification counts and outcomes by time bucket.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics transactions-graph

Inspect this command offline before preparing an operation:

akedly describe "analytics transactions-graph" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--interval`	enum	daily \| weekly \| monthly	Command-specific option; see the full command details below. Manifest body field: interval.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_tx_graph:read.

Server request: POST /analytics/graphTotalMainTransactions.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read verification counts and outcomes by time bucket for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics transactions-graph

verification counts and outcomes by time bucket for the login owner's account.

akedly analytics transactions-graph --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "graphData": [
      {
        "date": "2026-10-04",
        "transactionsNumber": 5,
        "successfulTransactions": 4,
        "failedTransactions": 1,
        "pendingTransactions": 0,
        "passkeyCount": 1,
        "passkeyShare": 20,
        "passkeyEnrolledCount": 1,
        "uniqueUsers": {
          "total": 2,
          "authenticated": 1,
          "successRate": 50
        }
      }
    ],
    "totpExcluded": false,
    "v12Excluded": false
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics transactions-graph --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "interval",
      "schema": {
        "type": "string",
        "enum": [
          "daily",
          "weekly",
          "monthly"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "interval",
          "transform": "identity",
          "role": "body",
          "input": "interval",
          "contributors": [
            "interval"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/graphTotalMainTransactions",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ],
      "interval": [
        {
          "path": "interval",
          "transform": "identity",
          "role": "body",
          "input": "interval",
          "contributors": [
            "interval"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "graphData": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "transactionsNumber": {
                  "type": "integer"
                },
                "successfulTransactions": {
                  "type": "integer"
                },
                "failedTransactions": {
                  "type": "integer"
                },
                "pendingTransactions": {
                  "type": "integer"
                },
                "passkeyCount": {
                  "type": "integer"
                },
                "passkeyShare": {
                  "type": "number"
                },
                "passkeyEnrolledCount": {
                  "type": "integer"
                },
                "uniqueUsers": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "authenticated": {
                      "type": "integer"
                    },
                    "successRate": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "total",
                    "authenticated",
                    "successRate"
                  ],
                  "additionalProperties": true
                }
              },
              "required": [
                "date",
                "transactionsNumber",
                "successfulTransactions",
                "failedTransactions",
                "pendingTransactions",
                "passkeyCount",
                "passkeyShare",
                "passkeyEnrolledCount",
                "uniqueUsers"
              ],
              "additionalProperties": true
            }
          },
          "totpExcluded": {
            "type": "boolean"
          },
          "v12Excluded": {
            "type": "boolean"
          }
        },
        "required": [
          "graphData",
          "totpExcluded",
          "v12Excluded"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics international-split

Read national/international/TOTP counts and costs using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need national, international and totp counts/costs to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/pieChartInternationalAndNational and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Exact endpoint behavior and scope caveats: Read national, international and TOTP counts and costs for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing national, international and totp counts/costs.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics international-split

Inspect this command offline before preparing an operation:

akedly describe "analytics international-split" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_graphs_intl_national:read.

Server request: POST /analytics/pieChartInternationalAndNational.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read national, international and TOTP counts and costs for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics international-split

national, international and TOTP counts/costs for the login owner's account.

akedly analytics international-split --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "national": {},
    "international": {},
    "totp": {}
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics international-split --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/pieChartInternationalAndNational",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics unique-users

Read unique end-user authentication counts using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need unique end-user counts/outcomes and full phone-number details to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/unique-users-authenticated and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. Returns userDetails with each end-user's full phone number; keep output private. For just the rates use --fields data.comparison.
Exact endpoint behavior and scope caveats: Count unique end-users and read their authentication outcomes for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. Returns userDetails with each end-user's full phone number; keep output private. For just the rates use --fields data.comparison.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing unique end-user counts/outcomes and full phone-number details.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics unique-users

Inspect this command offline before preparing an operation:

akedly describe "analytics unique-users" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_unique_users:read.

Server request: POST /analytics/unique-users-authenticated.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Count unique end-users and read their authentication outcomes for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. Returns userDetails with each end-user's full phone number; keep output private. For just the rates use --fields data.comparison.

Worked examples

Example analytics unique-users

unique end-user counts/outcomes and full phone-number details for the login owner's account.

akedly analytics unique-users --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "totalUniqueUsers": 1,
    "uniqueUsersAuthenticated": 1,
    "uniqueUserSuccessRate": 100,
    "comparison": {
      "perUniqueUser": {
        "successRate": 100,
        "authenticated": 1,
        "total": 1
      },
      "perTransaction": {
        "successRate": 100,
        "successful": 2,
        "total": 2
      }
    },
    "userDetails": [
      {
        "phoneNumber": "+201234567890",
        "totalTransactions": 2,
        "successfulTransactions": 2,
        "failedTransactions": 0,
        "authenticated": true
      }
    ],
    "totpExcluded": false,
    "v12Excluded": false
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics unique-users --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/unique-users-authenticated",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "totalUniqueUsers": {
            "type": "integer"
          },
          "uniqueUsersAuthenticated": {
            "type": "integer"
          },
          "uniqueUserSuccessRate": {
            "type": "number"
          },
          "comparison": {
            "type": "object",
            "properties": {
              "perUniqueUser": {
                "type": "object",
                "properties": {
                  "successRate": {
                    "type": "number"
                  },
                  "authenticated": {
                    "type": "integer"
                  },
                  "total": {
                    "type": "integer"
                  }
                },
                "required": [],
                "additionalProperties": true
              },
              "perTransaction": {
                "type": "object",
                "properties": {
                  "successRate": {
                    "type": "number"
                  },
                  "successful": {
                    "type": "integer"
                  },
                  "total": {
                    "type": "integer"
                  }
                },
                "required": [],
                "additionalProperties": true
              }
            },
            "required": [],
            "additionalProperties": true
          },
          "userDetails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phoneNumber": {
                  "type": "string"
                },
                "totalTransactions": {
                  "type": "integer"
                },
                "successfulTransactions": {
                  "type": "integer"
                },
                "failedTransactions": {
                  "type": "integer"
                },
                "authenticated": {
                  "type": "boolean"
                }
              },
              "required": [
                "phoneNumber",
                "totalTransactions",
                "successfulTransactions",
                "failedTransactions",
                "authenticated"
              ],
              "additionalProperties": true
            }
          },
          "totpExcluded": {
            "type": "boolean"
          },
          "v12Excluded": {
            "type": "boolean"
          }
        },
        "required": [
          "totalUniqueUsers",
          "uniqueUsersAuthenticated",
          "uniqueUserSuccessRate",
          "comparison",
          "userDetails",
          "totpExcluded",
          "v12Excluded"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics unique-users-graph

Read unique end-user authentication counts using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need unique-user authentication metrics by time bucket to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/unique-users-authenticated-graph and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view.
Exact endpoint behavior and scope caveats: Read unique-user authentication rates by time bucket for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing unique-user authentication metrics by time bucket.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics unique-users-graph

Inspect this command offline before preparing an operation:

akedly describe "analytics unique-users-graph" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--interval`	enum	daily \| weekly \| monthly	Command-specific option; see the full command details below. Manifest body field: interval.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_unique_users:read.

Server request: POST /analytics/unique-users-authenticated-graph.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read unique-user authentication rates by time bucket for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Interval defaults to daily; weekly and monthly use 7-day and 30-day buckets. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view.

Worked examples

Example analytics unique-users-graph

unique-user authentication metrics by time bucket for the login owner's account.

akedly analytics unique-users-graph --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "graphData": [
      {
        "date": "2026-10-04",
        "totalUniqueUsers": 1,
        "uniqueUsersAuthenticated": 1,
        "uniqueUserSuccessRate": 100,
        "transactionSuccessRate": 100,
        "totalTransactions": 2,
        "successfulTransactions": 2
      }
    ],
    "summary": {
      "totalIntervals": 1,
      "avgUniqueUserSuccessRate": 100,
      "avgTransactionSuccessRate": 100
    }
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics unique-users-graph --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "interval",
      "schema": {
        "type": "string",
        "enum": [
          "daily",
          "weekly",
          "monthly"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "interval",
          "transform": "identity",
          "role": "body",
          "input": "interval",
          "contributors": [
            "interval"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/unique-users-authenticated-graph",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "interval": [
        {
          "path": "interval",
          "transform": "identity",
          "role": "body",
          "input": "interval",
          "contributors": [
            "interval"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "graphData": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "totalUniqueUsers": {
                  "type": "integer"
                },
                "uniqueUsersAuthenticated": {
                  "type": "integer"
                },
                "uniqueUserSuccessRate": {
                  "type": "number"
                },
                "transactionSuccessRate": {
                  "type": "number"
                },
                "totalTransactions": {
                  "type": "integer"
                },
                "successfulTransactions": {
                  "type": "integer"
                }
              },
              "required": [
                "date",
                "totalUniqueUsers",
                "uniqueUsersAuthenticated",
                "uniqueUserSuccessRate",
                "transactionSuccessRate",
                "totalTransactions",
                "successfulTransactions"
              ],
              "additionalProperties": true
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "totalIntervals": {
                "type": "integer"
              },
              "avgUniqueUserSuccessRate": {
                "type": "number"
              },
              "avgTransactionSuccessRate": {
                "type": "number"
              }
            },
            "required": [
              "totalIntervals",
              "avgUniqueUserSuccessRate",
              "avgTransactionSuccessRate"
            ],
            "additionalProperties": true
          }
        },
        "required": [
          "graphData",
          "summary"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics countries

Read verification volume by country using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need verification totals grouped by country to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/getVerificationsByCountry and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Product defaults to otp; all includes OTP and utility. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
Exact endpoint behavior and scope caveats: Read verification counts by country for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Product defaults to otp; all includes OTP and utility. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing verification totals grouped by country.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics countries

Inspect this command offline before preparing an operation:

akedly describe "analytics countries" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_countries_bar:read.

Server request: POST /analytics/getVerificationsByCountry.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read verification counts by country for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last 30 days through now plus four hours. Product defaults to otp; all includes OTP and utility. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics countries

verification totals grouped by country for the login owner's account.

akedly analytics countries --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": [
    {
      "countryId": "EG",
      "name": "Egypt",
      "isoCode": "EG",
      "pending": 0,
      "successful": 3,
      "failed": 1,
      "total": 4,
      "channels": {
        "whatsapp": 3,
        "sms": 1,
        "telegram": 0,
        "email": 0
      },
      "channelStatus": {
        "whatsapp": {
          "successful": 2,
          "failed": 1
        },
        "sms": {
          "successful": 1,
          "failed": 0
        },
        "telegram": {
          "successful": 0,
          "failed": 0
        },
        "email": {
          "successful": 0,
          "failed": 0
        }
      }
    }
  ]
}

Additional command forms

akedly analytics countries --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/getVerificationsByCountry",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "countryId": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "isoCode": {
              "type": "string"
            },
            "pending": {
              "type": "integer"
            },
            "successful": {
              "type": "integer"
            },
            "failed": {
              "type": "integer"
            },
            "skipped": {
              "type": "integer"
            },
            "total": {
              "type": "integer"
            },
            "channels": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "integer"
                },
                "sms": {
                  "type": "integer"
                },
                "telegram": {
                  "type": "integer"
                },
                "email": {
                  "type": "integer"
                }
              },
              "required": [],
              "additionalProperties": true
            },
            "channelStatus": {
              "type": "object",
              "properties": {
                "whatsapp": {
                  "type": "object",
                  "properties": {
                    "successful": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    }
                  },
                  "required": [],
                  "additionalProperties": true
                },
                "sms": {
                  "type": "object",
                  "properties": {
                    "successful": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    }
                  },
                  "required": [],
                  "additionalProperties": true
                },
                "telegram": {
                  "type": "object",
                  "properties": {
                    "successful": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    }
                  },
                  "required": [],
                  "additionalProperties": true
                },
                "email": {
                  "type": "object",
                  "properties": {
                    "successful": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    }
                  },
                  "required": [],
                  "additionalProperties": true
                }
              },
              "required": [],
              "additionalProperties": true
            }
          },
          "required": [
            "countryId",
            "name",
            "isoCode",
            "pending",
            "successful",
            "failed",
            "total",
            "channels",
            "channelStatus"
          ],
          "additionalProperties": true
        }
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics passkeys

Read passkey adoption, methods and funnel using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need passkey adoption, method split, funnel and source split; bysource may be null if optional leg failed to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/passkey-analytics and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.
With a pipeline or widget scope, TOTP is omitted because it cannot be attributed; widget scope also omits V1.2 passkeys. This endpoint response does not include explicit exclusion booleans, so interpret scoped method totals as scoped OTP/passkey results rather than treating absent TOTP/V1.2 data as zero account-wide.
Exact endpoint behavior and scope caveats: Read passkey adoption, method split, funnel, potential savings and source split for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing passkey adoption, method split, funnel and source split; bysource may be null if optional leg failed.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics passkeys

Inspect this command offline before preparing an operation:

akedly describe "analytics passkeys" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_passkeys:read.

Server request: POST /analytics/passkey-analytics.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read passkey adoption, method split, funnel, potential savings and source split for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate is UTC midnight, not the end of that day. Without dates the server defaults to the last week through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id.

Worked examples

Example analytics passkeys

passkey adoption, method split, funnel and source split; bySource may be null if optional leg failed for the login owner's account.

akedly analytics passkeys --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "adoption": {
      "enrolledUsers": 2,
      "verifiedUsers": 4,
      "passkeyVerifications": 3,
      "totalVerifications": 10,
      "adoptionRate": 50,
      "usageShare": 30
    },
    "methods": {
      "totalVerifications": 10,
      "uniqueUsers": 4,
      "byMethod": {
        "otp": 5,
        "totp": 2,
        "passkey": 3
      }
    },
    "funnel": {
      "counts": {
        "offered": 4,
        "used": 3,
        "fellBack": 1,
        "enrollPromptShown": 2,
        "enrolled": 1,
        "enrollSkipped": 1,
        "enrollTimeout": 0
      },
      "authConversion": 75,
      "authConversionOfOffered": 75,
      "fallbackRate": 25,
      "enrollConversion": 50
    },
    "bySource": {
      "enrollments": {
        "v12": 1,
        "widget": 1,
        "total": 2
      },
      "verifications": {
        "v12": 2,
        "widget": 1,
        "total": 3
      }
    }
  }
}

Additional command forms

akedly analytics passkeys --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/passkey-analytics",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "adoption": {
            "type": "object",
            "properties": {
              "enrolledUsers": {
                "type": "integer"
              },
              "verifiedUsers": {
                "type": "integer"
              },
              "passkeyVerifications": {
                "type": "integer"
              },
              "totalVerifications": {
                "type": "integer"
              },
              "adoptionRate": {
                "type": "number"
              },
              "usageShare": {
                "type": "number"
              }
            },
            "required": [
              "enrolledUsers",
              "verifiedUsers",
              "passkeyVerifications",
              "totalVerifications",
              "adoptionRate",
              "usageShare"
            ],
            "additionalProperties": true
          },
          "methods": {
            "type": "object",
            "properties": {
              "totalVerifications": {
                "type": "integer"
              },
              "uniqueUsers": {
                "type": "integer"
              },
              "byMethod": {
                "type": "object",
                "properties": {
                  "otp": {
                    "type": "integer"
                  },
                  "totp": {
                    "type": "integer"
                  },
                  "passkey": {
                    "type": "integer"
                  }
                },
                "required": [
                  "otp",
                  "totp",
                  "passkey"
                ],
                "additionalProperties": true
              }
            },
            "required": [
              "totalVerifications",
              "uniqueUsers",
              "byMethod"
            ],
            "additionalProperties": true
          },
          "funnel": {
            "type": "object",
            "properties": {
              "counts": {
                "type": "object",
                "properties": {
                  "offered": {
                    "type": "integer"
                  },
                  "used": {
                    "type": "integer"
                  },
                  "fellBack": {
                    "type": "integer"
                  },
                  "enrollPromptShown": {
                    "type": "integer"
                  },
                  "enrolled": {
                    "type": "integer"
                  },
                  "enrollSkipped": {
                    "type": "integer"
                  },
                  "enrollTimeout": {
                    "type": "integer"
                  }
                },
                "required": [
                  "offered",
                  "used",
                  "fellBack",
                  "enrollPromptShown",
                  "enrolled",
                  "enrollSkipped",
                  "enrollTimeout"
                ],
                "additionalProperties": true
              },
              "authConversion": {
                "type": "number"
              },
              "authConversionOfOffered": {
                "type": "number"
              },
              "fallbackRate": {
                "type": "number"
              },
              "enrollConversion": {
                "type": "number"
              }
            },
            "required": [
              "counts",
              "authConversion",
              "authConversionOfOffered",
              "fallbackRate",
              "enrollConversion"
            ],
            "additionalProperties": true
          },
          "bySource": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "enrollments": {
                    "type": "object",
                    "properties": {
                      "v12": {
                        "type": "integer"
                      },
                      "widget": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "v12",
                      "widget",
                      "total"
                    ],
                    "additionalProperties": true
                  },
                  "verifications": {
                    "type": "object",
                    "properties": {
                      "v12": {
                        "type": "integer"
                      },
                      "widget": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "required": [
                      "v12",
                      "widget",
                      "total"
                    ],
                    "additionalProperties": true
                  }
                },
                "required": [
                  "enrollments",
                  "verifications"
                ],
                "additionalProperties": true
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "adoption",
          "methods",
          "funnel",
          "bySource"
        ],
        "additionalProperties": true
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics scope-options

Read selectable pipelines and widgets using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need owner-scoped names and ids for analytics filters; widgets may have null pipelineid to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/scope-options and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override.
Exact endpoint behavior and scope caveats: List selectable pipelines and widgets for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing owner-scoped names and ids for analytics filters; widgets may have null pipelineid.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics scope-options

Inspect this command offline before preparing an operation:

akedly describe "analytics scope-options" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_current_rates:read.

Server request: POST /analytics/scope-options.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

List selectable pipelines and widgets for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override.

Worked examples

Example analytics scope-options

owner-scoped names and ids for analytics filters; widgets may have null pipelineId for the login owner's account.

akedly analytics scope-options

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "pipelines": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "name": "Example OTP",
        "product": "otp"
      }
    ],
    "widgets": [
      {
        "widgetId": "widget_0123456789abcdef0123456789abcdef",
        "name": "Example widget",
        "pipelineId": null
      }
    ]
  }
}

Additional command forms

akedly analytics scope-options --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/scope-options",
    "query": {},
    "body": {},
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "pipelines": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "product": {
                  "type": "string"
                }
              },
              "required": [
                "_id",
                "name"
              ],
              "additionalProperties": true
            }
          },
          "widgets": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "widgetId": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "pipelineId": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "widgetId",
                "name",
                "pipelineId"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "pipelines",
          "widgets"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics utility

Read utility-send delivery and cost aggregates using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need utility notification volume, delivery, spend, channel, timeline and template aggregates to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/utility-analytics and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. Utility analytics aligns the supplied dates to whole UTC days, including the eDate day. Without dates the server defaults from UTC midnight a week ago through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view.
Exact endpoint behavior and scope caveats: Read utility-notification sends, delivery and spend for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. Utility analytics aligns the supplied dates to whole UTC days, including the eDate day. Without dates the server defaults from UTC midnight a week ago through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing utility notification volume, delivery, spend, channel, timeline and template aggregates.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics utility

Inspect this command offline before preparing an operation:

akedly describe "analytics utility" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_perf_utilities:read.

Server request: POST /analytics/utility-analytics.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read utility-notification sends, delivery and spend for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. Utility analytics aligns the supplied dates to whole UTC days, including the eDate day. Without dates the server defaults from UTC midnight a week ago through now plus four hours. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view.

Worked examples

Example analytics utility

utility notification volume, delivery, spend, channel, timeline and template aggregates for the login owner's account.

akedly analytics utility --start-date 2026-10-01 --end-date 2026-10-07

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "overview": {
      "totalSends": 10,
      "delivered": 8,
      "pending": 1,
      "failed": 1,
      "skipped": 0,
      "deliveryRate": 80,
      "acknowledged": 8,
      "ackRate": 80,
      "totalSpend": 5,
      "avgCostPerMessage": 0.5,
      "billedMessages": 10,
      "testSends": 1
    },
    "channels": {
      "whatsapp": {
        "totalSends": 9,
        "totalSpend": 4.5
      },
      "sms": {
        "totalSends": 1,
        "totalSpend": 0.5
      }
    },
    "timeline": [
      {
        "date": "2026-10-04",
        "totalSends": 10
      }
    ],
    "templates": [
      {
        "templateName": "verify_code",
        "count": 10
      }
    ]
  }
}

Additional command forms

akedly analytics utility --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/utility-analytics",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "overview": {
            "type": "object",
            "properties": {
              "totalSends": {
                "type": "integer"
              },
              "delivered": {
                "type": "integer"
              },
              "pending": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              },
              "skipped": {
                "type": "integer"
              },
              "deliveryRate": {
                "type": "number"
              },
              "acknowledged": {
                "type": "integer"
              },
              "ackRate": {
                "type": "number"
              },
              "totalSpend": {
                "type": "number"
              },
              "avgCostPerMessage": {
                "type": "number"
              },
              "billedMessages": {
                "type": "integer"
              },
              "testSends": {
                "type": "integer"
              }
            },
            "required": [],
            "additionalProperties": true
          },
          "channels": {
            "type": "object",
            "properties": {
              "whatsapp": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": true
              },
              "sms": {
                "type": "object",
                "properties": {},
                "required": [],
                "additionalProperties": true
              }
            },
            "required": [],
            "additionalProperties": true
          },
          "timeline": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "required": [],
              "additionalProperties": true
            }
          },
          "templates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {},
              "required": [],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "overview",
          "channels",
          "timeline",
          "templates"
        ],
        "additionalProperties": true
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics my-costs summary

Read billed cost amounts and breakdowns using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need granular-pricing cost summary with channel/provider breakdown to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/my-costs/summary and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.
Exact endpoint behavior and scope caveats: Read total cost, transaction count and channel/provider breakdowns for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing granular-pricing cost summary with channel/provider breakdown.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics my-costs summary

Inspect this command offline before preparing an operation:

akedly describe "analytics my-costs summary" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--channel`	text	—	Command-specific option; see the full command details below. Manifest body field: channel.
`--provider`	text	—	Command-specific option; see the full command details below. Manifest body field: provider.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_breakdown:read.

Server request: POST /analytics/my-costs/summary.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read total cost, transaction count and channel/provider breakdowns for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Worked examples

Example analytics my-costs summary

granular-pricing cost summary with channel/provider breakdown for the login owner's account.

akedly analytics my-costs summary --start-date 2026-10-01 --end-date 2026-10-07 --product utility

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "totalCost": 12.5,
    "transactionCount": 4,
    "byChannel": [
      {
        "channel": "sms",
        "count": 4,
        "totalCost": 12.5
      }
    ],
    "byProvider": [
      {
        "provider": "cequens",
        "count": 4,
        "totalCost": 12.5
      }
    ]
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics my-costs summary --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "channel",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    {
      "name": "provider",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/my-costs/summary",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "channel": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ],
      "provider": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. Monetary values are costs in EGP, not a wallet balance. Cost values are monetary amounts in EGP, not a wallet balance. These monetary cost values are EGP amounts, not wallet balances.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "status": {
        "const": "success"
      },
      "data": {
        "type": "object",
        "properties": {
          "totalCost": {
            "type": "number"
          },
          "transactionCount": {
            "type": "integer"
          },
          "byChannel": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "channel": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "totalCost": {
                  "type": "number"
                }
              },
              "required": [
                "channel",
                "count",
                "totalCost"
              ],
              "additionalProperties": true
            }
          },
          "byProvider": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "provider": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "totalCost": {
                  "type": "number"
                }
              },
              "required": [
                "provider",
                "count",
                "totalCost"
              ],
              "additionalProperties": true
            }
          }
        },
        "required": [
          "totalCost",
          "transactionCount",
          "byChannel",
          "byProvider"
        ],
        "additionalProperties": true
      },
      "message": {
        "type": "string"
      }
    },
    "required": [
      "status",
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics my-costs by-provider

Read billed cost amounts and breakdowns using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need granular-pricing cost grouped by provider to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/my-costs/by-provider and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.
Exact endpoint behavior and scope caveats: Read costs by provider for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing granular-pricing cost grouped by provider.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics my-costs by-provider

Inspect this command offline before preparing an operation:

akedly describe "analytics my-costs by-provider" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--channel`	text	—	Command-specific option; see the full command details below. Manifest body field: channel.
`--country`	text	—	Command-specific option; see the full command details below. Manifest body field: country.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_breakdown:read.

Server request: POST /analytics/my-costs/by-provider.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read costs by provider for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Worked examples

Example analytics my-costs by-provider

granular-pricing cost grouped by provider for the login owner's account.

akedly analytics my-costs by-provider --start-date 2026-10-01 --end-date 2026-10-07 --product utility

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "providers": [
      {
        "provider": "cequens",
        "count": 4,
        "totalCost": 12.5
      }
    ]
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics my-costs by-provider --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "channel",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    {
      "name": "country",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "country",
          "transform": "identity",
          "role": "body",
          "input": "country",
          "contributors": [
            "country"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/my-costs/by-provider",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "channel": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ],
      "country": [
        {
          "path": "country",
          "transform": "identity",
          "role": "body",
          "input": "country",
          "contributors": [
            "country"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics my-costs by-country

Read billed cost amounts and breakdowns using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need granular-pricing cost grouped by destination country to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/my-costs/by-country and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.
Exact endpoint behavior and scope caveats: Read costs by country for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing granular-pricing cost grouped by destination country.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics my-costs by-country

Inspect this command offline before preparing an operation:

akedly describe "analytics my-costs by-country" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--channel`	text	—	Command-specific option; see the full command details below. Manifest body field: channel.
`--provider`	text	—	Command-specific option; see the full command details below. Manifest body field: provider.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_breakdown:read.

Server request: POST /analytics/my-costs/by-country.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read costs by country for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Worked examples

Example analytics my-costs by-country

granular-pricing cost grouped by destination country for the login owner's account.

akedly analytics my-costs by-country --start-date 2026-10-01 --end-date 2026-10-07 --product utility

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "countries": [
      {
        "country": "EG",
        "count": 4,
        "totalCost": 12.5
      }
    ]
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics my-costs by-country --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "channel",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    {
      "name": "provider",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/my-costs/by-country",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "channel": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ],
      "provider": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics my-costs by-api-version

Read billed cost amounts and breakdowns using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need granular-pricing cost grouped by api version to monitor product usage, service outcomes or account spend.

How it works

The CLI sends the command's filters to /analytics/my-costs/by-api-version and injects the authenticated owner identity; it returns the controller's analytics payload without changing account data.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.
Exact endpoint behavior and scope caveats: Read costs by API version for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing granular-pricing cost grouped by api version.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics my-costs by-api-version

Inspect this command offline before preparing an operation:

akedly describe "analytics my-costs by-api-version" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--channel`	text	—	Command-specific option; see the full command details below. Manifest body field: channel.
`--provider`	text	—	Command-specific option; see the full command details below. Manifest body field: provider.
`--country`	text	—	Command-specific option; see the full command details below. Manifest body field: country.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_breakdown:read.

Server request: POST /analytics/my-costs/by-api-version.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read costs by API version for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Worked examples

Example analytics my-costs by-api-version

granular-pricing cost grouped by API version for the login owner's account.

akedly analytics my-costs by-api-version --start-date 2026-10-01 --end-date 2026-10-07 --product utility

Illustrative response (sensitive values omitted):

json

{
  "status": "success",
  "data": {
    "versions": [
      {
        "apiVersion": "v1.2",
        "count": 4,
        "totalCost": 12.5
      }
    ]
  },
  "message": "Data extracted successfully"
}

Additional command forms

akedly analytics my-costs by-api-version --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "channel",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    {
      "name": "provider",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ]
    },
    {
      "name": "country",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "country",
          "transform": "identity",
          "role": "body",
          "input": "country",
          "contributors": [
            "country"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/my-costs/by-api-version",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "channel": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ],
      "provider": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ],
      "country": [
        {
          "path": "country",
          "transform": "identity",
          "role": "body",
          "input": "country",
          "contributors": [
            "country"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics my-costs unified

Read billed cost amounts and breakdowns using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need combined cost summary and breakdowns to monitor product usage, service outcomes or account spend.

How it works

The CLI returns the backend response unchanged; this endpoint returns a root {data: ...} object without a status property.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On an Akedly staff (admin) account this view stays owner-scoped and skips the granular-pricing check. --widget-id is the public widget_<32 hex> id, not the Mongo _id. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.
Exact endpoint behavior and scope caveats: Read total cost and channel/provider/country/API-version breakdowns for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On an Akedly staff (admin) account this view stays owner-scoped and skips the granular-pricing check. --widget-id is the public widget_<32 hex> id, not the Mongo _id. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing combined cost summary and breakdowns.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics my-costs unified

Inspect this command offline before preparing an operation:

akedly describe "analytics my-costs unified" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--channel`	text	—	Command-specific option; see the full command details below. Manifest body field: channel.
`--provider`	text	—	Command-specific option; see the full command details below. Manifest body field: provider.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_breakdown:read.

Server request: POST /analytics/my-costs/unified.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read total cost and channel/provider/country/API-version breakdowns for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last week through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On an Akedly staff (admin) account this view stays owner-scoped and skips the granular-pricing check. --widget-id is the public widget_<32 hex> id, not the Mongo _id. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Worked examples

Example analytics my-costs unified

combined cost summary and breakdowns for the login owner's account.

akedly analytics my-costs unified --start-date 2026-10-01 --end-date 2026-10-07 --product utility

Illustrative response (sensitive values omitted):

json

{
  "data": {
    "totalCost": 12.5,
    "transactionCount": 4,
    "byChannel": [
      {
        "channel": "sms",
        "count": 4,
        "totalCost": 12.5
      }
    ],
    "byProvider": [
      {
        "provider": "cequens",
        "count": 4,
        "totalCost": 12.5
      }
    ],
    "byCountry": [
      {
        "country": "EG",
        "count": 4,
        "totalCost": 12.5
      }
    ],
    "byApiVersion": [
      {
        "apiVersion": "v1.2",
        "count": 4,
        "totalCost": 12.5
      }
    ]
  }
}

Additional command forms

akedly analytics my-costs unified --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "channel",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ]
    },
    {
      "name": "provider",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/my-costs/unified",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ],
      "channel": [
        {
          "path": "channel",
          "transform": "identity",
          "role": "body",
          "input": "channel",
          "contributors": [
            "channel"
          ]
        }
      ],
      "provider": [
        {
          "path": "provider",
          "transform": "identity",
          "role": "body",
          "input": "provider",
          "contributors": [
            "provider"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. The combined data includes billed/cost EGP amounts and breakdowns; field groups can be extended by the API. Monetary values are costs in EGP, not a wallet balance. Cost values are monetary amounts in EGP, not a wallet balance. The response is root {data} without status; the amount key is totalCost. These monetary cost values are EGP amounts, not wallet balances.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "data": {
        "type": "object",
        "properties": {
          "totalCost": {
            "type": "number"
          },
          "transactionCount": {
            "type": "integer"
          },
          "byChannel": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "channel": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "totalCost": {
                  "type": "number"
                }
              },
              "required": [
                "channel",
                "count",
                "totalCost"
              ],
              "additionalProperties": true
            }
          },
          "byProvider": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "provider": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "totalCost": {
                  "type": "number"
                }
              },
              "required": [
                "provider",
                "count",
                "totalCost"
              ],
              "additionalProperties": true
            }
          },
          "byCountry": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "totalCost": {
                  "type": "number"
                }
              },
              "required": [
                "country",
                "count",
                "totalCost"
              ],
              "additionalProperties": true
            }
          },
          "byApiVersion": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "apiVersion": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                },
                "totalCost": {
                  "type": "number"
                }
              },
              "required": [
                "apiVersion",
                "count",
                "totalCost"
              ],
              "additionalProperties": true
            }
          },
          "scopeDisclosure": {
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": true
          }
        },
        "required": [
          "totalCost",
          "transactionCount",
          "byChannel",
          "byProvider",
          "byCountry",
          "byApiVersion"
        ],
        "additionalProperties": true
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": true
  },
  "variants": [],
  "fieldSelection": {
    "flag": "fields",
    "behavior": "Selects comma-separated dot paths from the response root; for root arrays, paths apply to each element. Missing paths are omitted.",
    "sensitiveData": null
  }
}

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.

analytics my-costs total-spend

Read billed cost amounts and breakdowns using this endpoint's account scope. Customer sessions are limited to their own account; staff analytics scope varies by endpoint as its help text explains.

When to use

Use this when you need total spend and transaction count to monitor product usage, service outcomes or account spend.

How it works

The CLI returns the backend response unchanged; this endpoint returns a root {data: ...} object without a status property.
Date semantics, default windows, product scope, pipeline/widget scope and pricing restrictions are: the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last 30 days through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.
Exact endpoint behavior and scope caveats: Read total spend and transaction count for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last 30 days through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Prerequisites

An authenticated Akedly CLI session with the analytics permission for this command.
For a narrowed result, use an owned pipeline id or public widget_<32 hex> id as the command help specifies.

Expected outcome

A success response containing total spend and transaction count.

Next steps

Compare the result with the same product and time window before drawing trends.
Keep transaction lists and full user phone numbers private when this command returns them.

Usage

akedly analytics my-costs total-spend

Inspect this command offline before preparing an operation:

akedly describe "analytics my-costs total-spend" --output json

Flags

Flag	Type	Enum / range	Description
`--ksa`	boolean switch	—	Select the KSA deployment.
`--start-date`	text	—	Command-specific option; see the full command details below. Manifest body field: sDate.
`--end-date`	text	—	Command-specific option; see the full command details below. Manifest body field: eDate.
`--pipeline-id`	id	—	Command-specific option; see the full command details below. Manifest body field: pipelineID.
`--widget-id`	text	—	Command-specific option; see the full command details below. Manifest body field: widgetId.
`--product`	enum	all \| otp \| utility	Command-specific option; see the full command details below. Manifest body field: product.
`--dry-run`	boolean switch	—	Preview without sending the write or creating output files; planning reads may still occur. Bypass consent.
`--help`	boolean switch	—	Show offline command help.
`--output`	enum	json \| human	Select JSON or human output.
`--fields`	dot-paths	—	Select comma-separated safe dot paths; apply to each element of a root array.

Authentication, permission and guards

Auth: login. Permission: ana_cost_breakdown:read.

Server request: POST /analytics/my-costs/total-spend.

Shared server-guard guidance.

Consent

none. --dry-run bypasses confirmation where supported. Destructive: false. Spends money: false. Real send: false.

Retry

Output

Output: data. API output is pass-through server data unless the command details describe a CLI shape. Local commands, composites and hand-offs use their documented CLI shapes.

Full command details

Read total spend and transaction count for the login owner; the CLI injects userID. Read-only logins are supported. No targetUserID or allTime override. Dates are ISO text validated by the server, capped at 30 whole UTC calendar days. A date-only eDate includes the whole UTC day. Without dates the server defaults to the last 30 days through now plus four hours. Product defaults to otp; all includes OTP and utility. Non-granular OTP/all cost requests can return HTTP 403: Cost breakdown is only available for granular pricing users; utility-only requests do not require granular pricing. On an Akedly staff (admin) account analytics can cover all accounts; do not use it for an owner-only view. --widget-id is the public widget_<32 hex> id, not the Mongo _id. On legacy pricing, read spend with akedly analytics billing-consumption instead (or pass --product utility); an admin cannot grant this view.

Worked examples

Example analytics my-costs total-spend

total spend and transaction count for the login owner's account.

akedly analytics my-costs total-spend --start-date 2026-10-01 --end-date 2026-10-07 --product utility

Illustrative response (sensitive values omitted):

json

{
  "data": {
    "totalCost": 12.5,
    "transactionCount": 4
  }
}

Additional command forms

akedly analytics my-costs total-spend --dry-run

Input and file contracts

json

{
  "flagTokenEncoding": {
    "booleans": "A boolean schema describes switch presence: write --flag with no value.",
    "valuedFlags": "A string schema describes the single argv token after --flag or after --flag=; numeric token schemas parse as decimal strings and validation.parsedValueSchema documents the converted number.",
    "csvFlags": "A list schema describes one comma-separated argv token, not multiple shell arguments.",
    "projection": "--fields is one comma-separated argv token of safe dot paths and changes returned output only."
  },
  "positionals": [],
  "flags": [
    {
      "name": "help",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "output",
      "schema": {
        "type": "string",
        "enum": [
          "json",
          "human"
        ]
      },
      "required": false
    },
    {
      "name": "fields",
      "schema": {
        "type": "string",
        "pattern": "^(?!.*(?:^|[.,])(?:__proto__|constructor|prototype)(?:[.,]|$))(?!,)(?!.*,,)(?!.*,$)[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*(?:,[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*)*$"
      },
      "required": false,
      "validation": {
        "syntax": "Comma-separated safe dot paths; reserved prototype keys are refused."
      }
    },
    {
      "name": "ksa",
      "schema": {
        "type": "boolean"
      },
      "required": false
    },
    {
      "name": "start-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ]
    },
    {
      "name": "end-date",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ]
    },
    {
      "name": "pipeline-id",
      "schema": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{24}$"
      },
      "required": false,
      "wire": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "validation": {
        "syntax": "24-digit hexadecimal object ID."
      }
    },
    {
      "name": "widget-id",
      "schema": {
        "type": "string"
      },
      "required": false,
      "wire": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ]
    },
    {
      "name": "product",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "otp",
          "utility"
        ]
      },
      "required": false,
      "wire": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    {
      "name": "dry-run",
      "schema": {
        "type": "boolean"
      },
      "required": false,
      "input": {
        "role": "local-control",
        "purpose": "dry-run",
        "validationBoundary": "No separately curated semantic file schema is available; use the local reader contract and command help to understand additional handler or server validation."
      },
      "wire": [
        {
          "role": "local",
          "input": "dry-run",
          "inputRole": "local-control",
          "transform": "identity",
          "purpose": "dry-run",
          "contributors": [
            "dry-run"
          ]
        }
      ]
    }
  ],
  "files": [],
  "wire": {
    "method": "POST",
    "route": "/analytics/my-costs/total-spend",
    "query": {},
    "body": {
      "start-date": [
        {
          "path": "sDate",
          "transform": "identity",
          "role": "body",
          "input": "start-date",
          "contributors": [
            "start-date"
          ]
        }
      ],
      "end-date": [
        {
          "path": "eDate",
          "transform": "identity",
          "role": "body",
          "input": "end-date",
          "contributors": [
            "end-date"
          ]
        }
      ],
      "pipeline-id": [
        {
          "path": "pipelineID",
          "transform": "identity",
          "role": "body",
          "input": "pipeline-id",
          "contributors": [
            "pipeline-id"
          ]
        }
      ],
      "widget-id": [
        {
          "path": "widgetId",
          "transform": "identity",
          "role": "body",
          "input": "widget-id",
          "contributors": [
            "widget-id"
          ]
        }
      ],
      "product": [
        {
          "path": "product",
          "transform": "identity",
          "role": "body",
          "input": "product",
          "contributors": [
            "product"
          ]
        }
      ]
    },
    "ownerParams": []
  }
}

Response contract

Analytics payload substructures are extensible; the schema enumerates stable endpoint-level keys observed in the backend, with unknown additive fields preserved. Monetary values are costs in EGP, not a wallet balance. Cost values are monetary amounts in EGP, not a wallet balance. The response is root {data} without status; the amount key is totalCost. These monetary cost values are EGP amounts, not wallet balances.

json

{
  "schema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
      "status",
      "code",
      "message",
      "httpStatus",
      "hint"
    ],
    "properties": {
      "status": {
        "const": "error"
      },
      "code": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "httpStatus": {
        "type": [
          "integer",
          "null"
        ]
      },
      "details": {
        "anyOf": [
          {
            "type": "object",
            "minProperties": 1
          },
          {
            "type": "array",
            "minItems": 1
          }
        ]
      },
      "hint": {
        "type": "string"
      }
    },
    "additionalProperties": false
  },
  "globalHints": {
    "TOTP_DELETE_RECONCILIATION_PENDING": "Any Pending request blocks deletion, including one just opened; Failed requests can block too. Ordinary unverified, unbilled requests expire about five minutes after creation and normally become Expired on the next five-minute reconciliation run, within about ten minutes of creation; job delays or billing/counter recovery can extend that wait. Check the stored status in akedly totp history list; computed isExpired alone does not unblock deletion. Ask Akedly support if a request stays Pending or Failed beyond that normal window, or is Verified and still blocks.",
    "CLI_SECRET_ALREADY_DELIVERED": "Run akedly login again.",
    "CLI_LOGIN_INVALID": "Run akedly login.",
    "PERMISSION_DENIED": "If details.permission names a permission, ask an organization admin to grant it to your role. Otherwise read the server message: an organization admin cannot clear refusals such as an inactive or unverified account, an Akedly-managed global role, a reported-invitation pause or missing enterprise entitlement; follow the message or contact Akedly support. If the message says BYO-SMS is not enabled for this account, the account needs BYO-SMS entitlement and granular pricing; akedly whoami shows user.byoSmsEntitled and user.pricingModel, and only Akedly can change either.",
    "ORG_ADMIN_REQUIRED": "If the message asks for an active organization session, run akedly login and approve it with the intended organization active in the dashboard. If it says organization admin access is required, ask an organization admin for access or to run the command. Role changes can take up to 60 seconds to apply.",
    "OWNER_REQUIRED": "Only the account owner can do this; an organization admin is not necessarily the owner. Ask the owner to run it from their own login. For seats, organization admins can read akedly seats visibility; akedly seats status is owner-only.",
    "LOGIN_REQUIRED": "Run akedly login. If you supplied a credential, check --ksa or AKEDLY_REGION.",
    "CLI_DISABLED": "Customer CLI access is turned off on this Akedly server. Try again later or contact Akedly support.",
    "CLI_IDENTITY_UNAVAILABLE": "Akedly could not confirm your login right now. Wait a minute and try again.",
    "CLI_LOGIN_INDEX_UNAVAILABLE": "CLI login is temporarily unavailable on this server. Try again later or contact Akedly support.",
    "WABA_PHONE_CHECK_UNAVAILABLE": "Meta did not confirm the number. Wait a few minutes, then run the command again.",
    "CLI_UPGRADE_REQUIRED": "Install the latest @akedly/cli.",
    "NOT_AVAILABLE_ON_SERVER": "Check the selected region or ask an operator to deploy CLI support.",
    "CLI_RATE_LIMITED": "Wait before trying again.",
    "CLI_LOGIN_DENIED": "Run akedly login again and approve the new code.",
    "CLI_LOGIN_REQUEST_EXPIRED": "Run akedly login again.",
    "LOGIN_TIMEOUT": "Run akedly login again and approve before the timeout.",
    "CLI_READ_ONLY": "This login is read-only. Run akedly login and choose Full access.",
    "CLI_LOGIN_LIMIT_REACHED": "Run akedly cli-logins list, then akedly cli-logins end <id>",
    "CLI_LOGIN_NOT_FOUND": "Run akedly cli-logins list and check the login id.",
    "CLI_LOGIN_OWNER_PROTECTED": "Ask the account owner to end this login.",
    "IMPERSONATION_BLOCKED": "This login was approved by Akedly staff and can't do this. Run akedly login and approve it in your own dashboard session.",
    "SELF_IDENTITY_REQUIRED": "Personal settings need your own login. Run akedly login and approve it in your own dashboard session.",
    "MEMBER_NOT_FOUND": "Check the email with akedly team members list; a pending invitation is not a member yet.",
    "MEMBER_AMBIGUOUS": "Pass the memberId from akedly team members list instead of the email.",
    "API_KEY_ACTIVE_CAP_REACHED": "Revoke an unused key before creating another.",
    "API_KEY_ISSUANCE_DISABLED": "Ask an operator to enable API-key issuance.",
    "API_KEY_VERSION_CONFLICT": "List the keys and retry the edit with the current version.",
    "API_KEY_BUDGET_CONFIRMATION_REQUIRED": "Review the reduction and pass --confirm-budget-reduction.",
    "API_KEY_ISSUE_RECOVERY_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_TRANSITION_UNAVAILABLE": "Revoke the key and create a new one.",
    "API_KEY_ISSUE_IDEMPOTENCY_CONFLICT": "Use a new idempotency key for different issue details.",
    "API_KEY_SCOPE_NOT_ACTIVE": "Ask an operator to enable API-key scope editing.",
    "API_KEY_BUDGET_NOT_ACTIVE": "Ask an operator to enable API-key budget editing.",
    "API_KEY_NOT_FOUND": "Run akedly api-keys list and check the id.",
    "API_KEY_BUDGET_RACE": "List the keys and retry.",
    "V1_CREATION_NOT_ENTITLED": "V1 pipelines are not available to this account. Omit --api-version to create a V1.2 pipeline.",
    "SECRET_SUFFIX_REQUIRED": "Pass exactly one of --secret-file <saved path> or --secret-suffix <last 4 characters>.",
    "SECRET_SUFFIX_MISMATCH": "Reveal the current secret to --secret-file <new path> with akedly pipelines webhook-secret reveal <id> for webhook secrets, or akedly utilities pipelines signing-secret reveal <id> for utility request-signing secrets, then acknowledge with exactly one of --secret-file <that path> or --secret-suffix <last 4 characters>.",
    "CHANNEL_CHOICE_NOT_AVAILABLE": "Nothing in this request was saved. Each value in details.blockers names what is missing: not_entitled means Channel Choice isn't enabled on the account yet; legacy_pricing means the account needs granular pricing; not_pay_per_message means the pipeline is not billed per message, because it is billed per successful verification or the account has no billing plan yet; account_excluded and global_switch_off mean Channel Choice isn't offered to this account right now. Only Akedly can change these, so contact Akedly. utility_pipeline means utility pipelines have no Channel Choice. Resend any other changes without the Channel Choice flags.",
    "VERIFICATION_METHOD_UNAVAILABLE": "Nothing was saved. details.method is the word you typed, or the method's id if the method became unavailable after the CLI checked; running the command again rechecks the list and names the word. Remove that method from --verification-methods and retry, or contact Akedly if you expected it to be available.",
    "VERIFICATION_METHODS_REQUIRED": "A pipeline that has verification methods must keep at least one. Send the methods to keep instead of an empty list, for example akedly pipelines update <id> --verification-methods whatsapp,sms --yes.",
    "SETTING_NOT_FOR_THIS_PIPELINE": "Nothing in this request was saved. details.setting names the setting and details.useInstead what to use instead. For rate limits and the circuit breaker, reason api-version means this is a V1 or V2 pipeline, where they belong to a widget instead, so useInstead is widgets update. A widget must be attached to this pipeline first. Find attached widgets with akedly widgets list-filtered --pipeline-id <pipelineId>, then inspect the intended widget with akedly widgets get <widgetId>, using its 24-hex _id. This listing excludes inactive widgets by default. Also run akedly widgets list-filtered --pipeline-id <pipelineId> --status inactive before concluding that no widget is attached. Change its limits with akedly widgets update <widgetId> --rate-limits-file <file> --yes; use the widget file shape, not the pipeline file shape. Set its breaker with akedly widgets update <widgetId> --circuit-breaker on --yes (or off), and use --circuit-breaker-file <file> for widget thresholds and suspension durations; pipeline --circuit-breaker-sensitivity does not apply to widgets. If no widget is attached, create one with akedly widgets create --name <name> --pipeline-id <pipelineId> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <pipelineId> --yes. V2 attachment requires both callback URLs; V1 attachment requires entitlement. pipelines update now routes shared rate-limit, breaker and PoW flags to every attached widget on V1/V2. V1.2-only controls remain refused on V1/V2. Use the appropriate file shape for the resulting API version. For the Channel Choice widget experience, reason api-version means it needs a V2 pipeline, so create one with akedly pipelines create --name <name> --api-version v2 --redirect-url <url> --webhook-url <url> --secret-file <new path>, then attach a widget to it; reason no-widget means it needs a widget attached to this V2 pipeline, so create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, or attach an existing one with akedly widgets update <widgetId> --pipeline-id <id> --yes, then retry. Resend any other changes without that flag.",
    "PIPELINE_CHANGED": "Another change landed first, so nothing was saved. Run the same command again; if you changed rate limits or destination countries, it reads the pipeline again first and merges your change onto the new version. Run akedly pipelines get <id> to see what changed.",
    "RATE_LIMIT_INVALID": "Check details.field and any details.errors. Use whole numbers above zero in the expected JSON object shape. Pipeline --rate-limits-file uses perPhoneNumber, perIpAddress and perPipeline; widget --rate-limits-file uses widgetAttempts and otpRequests, each with perPhoneNumber, perDevice and perWidget. Each takes perMinute, perHour and perDay. Widget --circuit-breaker-file uses floodThresholds and suspensionSeconds; durations are whole seconds. Correct the named field and rerun the command.",
    "EXPECTED_UPDATED_AT_INVALID": "The CLI reads the revision automatically. Run the command again to read the current settings; if this continues, check that the CLI and server are up to date and contact Akedly support. Do not invent a revision or remove the conflict check.",
    "DESTINATION_COUNTRIES_MODE_REQUIRED": "Nothing in this request was saved. A changed country list under mode all would be discarded: pass --destination-countries-mode only-selected or all-except-selected with --destination-countries, or leave the list out to keep every country open. --destination-countries-mode all on its own clears the list.",
    "NOT_ENOUGH_TRAFFIC": "Keep the current limits for now. Recommended limits need at least 100 analysed requests and better than low confidence; try again after more real traffic or with a longer --period such as last-quarter, or set limits yourself with --rate-limits-file.",
    "INVALID_COUNTRY_POLICY": "Nothing in this request was saved. Use two-letter country codes such as EG,SA with --destination-countries and a mode of all, only-selected or all-except-selected; the message names the problem.",
    "OTP_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "TURNSTILE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_PIPELINE_CHANGED": "Another change landed first. Run akedly pipelines get <id> and retry.",
    "CLUSTER_GATE_NOT_AVAILABLE": "Nothing in this request was saved. Act on details.reason: not-offered means Cluster Gate is not offered for this pipeline right now, for example on a utility pipeline or in the KSA region; attaching a widget will not help on a V1.2 pipeline, because V1.2 pipelines cannot be attached to widgets; drop the Cluster Gate flags and resend any other changes; no-widget means Cluster Gate applies here only through a widget and none is attached, so attach an existing widget with akedly widgets update <widgetId> --pipeline-id <id> --yes, or create one with akedly widgets create --name <name> --pipeline-id <id> --secret-file <new path>, then retry; the pipeline must first be active, with both callback URLs and a verification method, and WIDGET_PIPELINE_NOT_READY says what is missing; on-create comes only from raw API requests that set Cluster Gate while creating a pipeline: create the pipeline first, then set Cluster Gate with akedly pipelines update <id> --cluster-gate on --cluster-gate-position balanced --yes; check-failed means availability could not be checked, so retry later; intent-missing comes only from raw API requests that omit clusterGateIntent: true.",
    "SECRET_ALREADY_ACKNOWLEDGED": "The secret was already acknowledged and cannot be shown again. Use the saved copy from pipeline creation (webhook secrets) or from reveal, for example the file written with --secret-file. Only if that copy is lost, use akedly pipelines webhook-secret regenerate <id> --yes --secret-file <new path> for webhook secrets, or akedly utilities pipelines signing-secret regenerate <id> --yes --secret-file <new path> for utility request-signing secrets. Regenerating stops the current secret immediately; deploy the new secret before using signed requests or accepting signed webhooks.",
    "WIDGET_PIPELINE_NOT_READY": "Fix each item in details.missing with akedly pipelines update <pipelineId> --status active --redirect-url <url> --webhook-url <url> --verification-methods whatsapp,sms,email --yes, passing only the flags for the missing items, then retry.",
    "WIDGET_IDENTITY_INDEX_UNAVAILABLE": "Widget identity indexes are unavailable. Retry later or contact Akedly support.",
    "INCOMPLETE_DATE_RANGE": "Supply both --start-date and --end-date, or neither.",
    "DATE_RANGE_TOO_LARGE": "Choose a date range of at most 30 days, counted as the command help describes.",
    "INVALID_DATE_RANGE": "Check both date bounds and their order.",
    "INVALID_DATE": "Use valid ISO dates for the requested range.",
    "NEEDS_BROWSER": "Turn Turnstile off for the pipeline in the dashboard, or run akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes.",
    "SETUP_REQUIRED": "Finish phone setup on the Personal Notifications page of your Akedly dashboard, then retry.",
    "INVALID_API_KEY": "Check the API key: akedly api-keys list, or create one with akedly api-keys create --label <name> --save --yes.",
    "API_KEY_SCOPE_DENIED": "This API key is scoped to other pipelines; use a key that includes this pipeline.",
    "MAX_ATTEMPTS_EXCEEDED": "Too many wrong codes; send a new OTP.",
    "ALREADY_VERIFIED": "This request is already verified; check it with akedly transactions status.",
    "INVALID_OTP": "Check the code and retry; attempts are limited.",
    "PIPELINE_INACTIVE": "Run akedly pipelines update <pipelineId> --status active --yes, then retry.",
    "POW_CHALLENGE_EXPIRED": "Run the command again; it fetches a fresh challenge.",
    "POW_CHALLENGE_REPLAYED": "Run the command again; it fetches a fresh challenge.",
    "POW_DIFFICULTY_STALE": "Run the command again; it fetches a fresh challenge.",
    "STATUS_LOOKUP_RATE_LIMITED": "Wait for the retryAfter seconds in details, then retry; each lookup counts against the 300 ids per minute limit.",
    "TRANSACTION_EXPIRED": "This code or request has expired; send a new one.",
    "USE_V1_2_ENDPOINT": "This pipeline is V1.2. Use akedly otp v1.2 send.",
    "SIGNATURE_EXPIRED": "This machine's clock differs from the server's by more than 60 seconds. Fix the clock and run the command again; it signs a fresh request each time.",
    "WIDGET_USER_MISMATCH": "This API key belongs to a different account than the widget. Use a key from the widget owner's account.",
    "WEBHOOK_SIGNATURE_INVALID": "Use the pipeline's current whsec_ secret (regenerating invalidates the old one), the exact raw body bytes the server received (no re-serialising, no trailing newline), and the svix-id, svix-timestamp and svix-signature headers.",
    "WAIT_EXPIRED": "The request expired before it was verified; it cannot complete. Start a new one (otp v2 attempt, otp v1.2 send or otp v1 create).",
    "WAIT_FAILED": "The verification failed and cannot complete; start a new one.",
    "WAIT_TIMEOUT": "The wait ended; the verification may still complete. Check it with akedly transactions status. Resume with akedly transactions status --attempt-id <id> --wait (or --transaction-id <id> --wait).",
    "WEBHOOK_TIMESTAMP_STALE": "The webhook timestamp is outside the allowed window. Check this machine's clock, or pass --at <unix seconds> to check an older delivery, or --tolerance-seconds <seconds>.",
    "WEBHOOK_HEADERS_MISSING": "Pass a headers JSON file with the svix-id, svix-timestamp and svix-signature headers exactly as received.",
    "NO_USABLE_API_KEY": "This account has no usable API key for this pipeline. Create one with akedly api-keys create --label <name> --save --yes; a key scoped to selected pipelines must include this pipeline.",
    "INVALID_API_VERSION": "This command does not support this pipeline's API version. Check it with akedly pipelines get <id> and use the matching command for that version.",
    "DOCTOR_FAILED": "Fix the failed checks in details.checks, then run akedly doctor again.",
    "PAGINATION_LIMIT": "Narrow the filters, for example a date range or status, or raise --limit (maximum 100), then run again.",
    "PAGINATION_STALLED": "The list changed while it was being read, or the server stopped advancing. Run the command again.",
    "REPORT_NOT_FOUND": "Run akedly reports list and check the reportId.",
    "DAILY_LIMIT_REACHED": "Wait until an earlier successful, sent or in-flight report generation leaves the rolling 24-hour window; for example, a generation at 14:00 stops counting after 14:00 the next day. This limit covers the whole account, including dashboard and teammate generations.",
    "REPORT_IN_PROGRESS": "A report is already generating for this account; dashboard and teammate generations share the same slot. Run akedly reports list before trying again.",
    "TEMPLATE_DUPLICATE": "Run akedly whatsapp otp-templates list; recover missing languages with update --add-languages instead of adding the same template again.",
    "TEMPLATE_LIMIT_REACHED": "Archive an unused template with akedly whatsapp otp-templates delete <id> --yes before adding another; the limit is 20 per WABA.",
    "TEMPLATE_PROVISIONING_FAILED": "The template or changes are saved. Run akedly whatsapp otp-templates list, then update <id> --add-languages <failed languages> rather than creating again.",
    "TEMPLATE_WABA_REQUIRED": "Connect an active own WhatsApp Business Account in the dashboard before managing OTP templates; check akedly whatsapp status.",
    "TEMPLATE_WABA_CHANGED": "This template belongs to the previous WABA. Add it again for the currently connected account.",
    "COUNTRY_CATALOG_UNAVAILABLE": "The country catalog is temporarily unavailable. Try again later.",
    "NOT_A_UTILITY_PIPELINE": "Choose an owned utility pipeline from akedly pipelines list, or create one with akedly pipelines create --product utility --name <name>.",
    "TEST_RATE_LIMITED": "Wait for Retry-After before testing again; account, recipient or replay safety limits may apply. Reuse the same Vodafone idempotencyKey when checking an existing attempt.",
    "EGRESS_FINGERPRINT_STALE": "The sending address changed. Run akedly byo-sms vodafone readiness, check the new address list, then acknowledge again with the new fingerprint.",
    "VODAFONE_EGRESS_NOT_READY": "Run akedly byo-sms vodafone readiness; ask Akedly support to verify the outbound addresses before acknowledging.",
    "UNROUTABLE_COUNTRY": "Run akedly byo-sms countries and choose routable country codes; use ALL alone for catch-all coverage.",
    "SOURCE_COVERAGE_UNROUTABLE": "Update the source integration countries using akedly byo-sms countries, then clone again.",
    "INVALID_TEST_PHONE": "Supply --test-phone-number in international format or update the saved test destination.",
    "TEST_PHONE_OUT_OF_COVERAGE": "Choose a test number in the integration countries, or update its countries before testing.",
    "VODAFONE_TEST_GUARD_UNAVAILABLE": "No new test was sent. Retry with the same idempotencyKey; contact Akedly support if send protection remains unavailable.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_REQUIRED": "Supply --idempotency-key with a unique request key and reuse it after an uncertain response.",
    "VODAFONE_TEST_IDEMPOTENCY_KEY_INVALID": "Supply --idempotency-key with 1 to 255 characters.",
    "VODAFONE_ACCEPTED_RETEST_INVALID": "Supply --previous-test-key with the accepted test key before requesting another test.",
    "VODAFONE_ACCEPTED_RETEST_REQUIRED": "Check akedly byo-sms get <id>; to send again after an accepted result, supply --previous-test-key and a new --idempotency-key with --yes.",
    "VODAFONE_NEW_TEST_CONFIRMATION_REQUIRED": "Check the previous result with akedly byo-sms get <id>; --allow-new-after-unknown with a new --idempotency-key and --yes can send another message.",
    "VODAFONE_NEW_TEST_IN_PROGRESS": "Wait for the current Vodafone test result; inspect akedly byo-sms get <id> before starting another attempt.",
    "BYO_SMS_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "VODAFONE_CONFIGURATION_CHANGED": "Run akedly byo-sms get <id>, test the current configuration, then try activation again.",
    "BYO_SMS_STEPS_INVALID": "Check the steps JSON and secret names; secret and extraction names use letters, numbers and underscore."
  },
  "commandHints": {},
  "hintPrecedence": [
    "explicit handler hint",
    "command-specific hint",
    "global code hint",
    "HTTP 429 fallback",
    "generic command-help fallback"
  ],
  "exitCodes": {
    "USAGE": 64,
    "CONFIRMATION_REQUIRED": 65,
    "LOGIN_REQUIRED": 66,
    "PERMISSION_DENIED": 67,
    "ORG_ADMIN_REQUIRED": 67,
    "OWNER_REQUIRED": 67,
    "CLI_READ_ONLY": 67,
    "IMPERSONATION_BLOCKED": 67,
    "SELF_IDENTITY_REQUIRED": 67,
    "CLI_LOGIN_OWNER_PROTECTED": 67,
    "NEEDS_BROWSER": 68,
    "SETUP_REQUIRED": 68,
    "CLI_RATE_LIMITED": 69,
    "NOT_AVAILABLE_ON_SERVER": 70,
    "CLI_UPGRADE_REQUIRED": 70,
    "CLI_DISABLED": 70
  }
}

Common error guidance.