Enhance usage API by exposing Analytics data

[piyushryn]

Proposing these points

• Clean uniform row shape (value, requests, bandwidthBytes) across every breakdown
  • value can be anything from url to countryName to error code
  • requests are the number of requests
  • bandwithBytes is the bandwidth in bytes
• topBreakdownsByRequest and topBreakdownsByBandwidth as the two top-level sort buckets, visible duplication but a cleaner approach (we can also start accepting a sorting key to return bandwidth and requests separatly rather than a monolith response with both kinds of sorting )

Old response of the api

{
    "bandwidthBytes": 18273487,
    "mediaLibraryStorageBytes": 697650923,
    "videoProcessingUnitsCount": 232,
    "extensionUnitsCount": 0,
    "originalCacheStorageBytes": 0
}

Proposed new New Response Types

interface UsageReport {
  meta: UsageMeta;
  bandwidthBytes: Bytes;
  mediaLibraryStorageBytes: Bytes;
  videoProcessingUnitsCount: number;
  extensionUnitsCount: number;
  originalCacheStorageBytes: Bytes;
  requestCount: RequestCount;
  videoProcessingUnitsUsage: VideoProcessingUnitsUsage;
  extensionUnitsUsage: ExtensionUnitsUsage;
  topBreakdownsByRequest: TopBreakdowns;
  topBreakdownsByBandwidth: TopBreakdowns;
}

type DateString = string; // Example: "2026-06-01"
type Bytes = number;
type RequestCount = number;

interface UsageMeta {
  from: DateString;
  to: DateString;
}
interface VideoProcessingUnitsUsage {
  SD: number;
  HD: number;
  "4K": number;
  "8K": number;
  "16K": number;
}
interface ExtensionUnitsUsage {
  total: number;
  "aws-auto-tagging": number;
  "google-auto-tagging": number;
  "ai-auto-description": number;
  ikremovebg: number;
  "remove-bg": number;
  upscale: number;
  retouch: number;
  genvar: number;
  genfill: number;
  genimg: number;
  dropshadow: number;
  "change-bg": number;
  edit: number;
  "ai-tasks": number;
  "ai-video-transcription": number;
  "creative-banner": number;
}
interface BreakdownItem {
  value: string;
  requests: RequestCount;
  bandwidthBytes: Bytes;
}
interface GeographyBreakdownItem extends BreakdownItem {
  countryCode: string; // Example: "IN", "SG"
}

export interface TopBreakdowns {
  statusCodes: BreakdownItem[];
  formats: BreakdownItem[];
  cache: BreakdownItem[];
  geography: GeographyBreakdownItem[];
  devices: BreakdownItem[];
  transformations: BreakdownItem[];
  images: BreakdownItem[];
  videos: BreakdownItem[];
  others: BreakdownItem[];
  referral: BreakdownItem[];
  videoTransformations: BreakdownItem[];
  resultType: BreakdownItem[];
  userAgents: BreakdownItem[];
}

Proposed new New Response Example

{
  "meta": {
    "from": "2026-06-01",
    "to": "2026-06-26"
  },
  "bandwidthBytes": 18273487,
  "mediaLibraryStorageBytes": 697650923,
  "videoProcessingUnitsCount": 232,
  "extensionUnitsCount": 0,
  "originalCacheStorageBytes": 0,
  "requestCount": 160,
  "videoProcessingUnitsUsage": {
    "SD": 232,
    "HD": 0,
    "4K": 0,
    "8K": 0,
    "16K": 0
  },
  "extensionUnitsUsage": {
    "total": 0,
    "aws-auto-tagging": 0,
    "google-auto-tagging": 0,
    "ai-auto-description": 0,
    "ikremovebg": 0,
    "remove-bg": 0,
    "upscale": 0,
    "retouch": 0,
    "genvar": 0,
    "genfill": 0,
    "genimg": 0,
    "dropshadow": 0,
    "change-bg": 0,
    "edit": 0,
    "ai-tasks": 0,
    "ai-video-transcription": 0,
    "creative-banner": 0
  },
  "topBreakdownsByRequest": {
    "statusCodes": [
      {
        "value": "200",
        "requests": 148,
        "bandwidthBytes": 13924675
      },
      {
        "value": "404",
        "requests": 7,
        "bandwidthBytes": 4250
      },
      {
        "value": "206",
        "requests": 4,
        "bandwidthBytes": 4344030
      }
    ],
    "formats": [
      {
        "value": "image/webp",
        "requests": 119,
        "bandwidthBytes": 5261379
      },
      {
        "value": "image/jpeg",
        "requests": 20,
        "bandwidthBytes": 4570132
      },
      {
        "value": "video/webm",
        "requests": 8,
        "bandwidthBytes": 6727289
      }
    ],
    "cache": [
      {
        "value": "Miss",
        "requests": 96,
        "bandwidthBytes": 12276318
      },
      {
        "value": "Hit",
        "requests": 56,
        "bandwidthBytes": 5992387
      },
      {
        "value": "Error",
        "requests": 8,
        "bandwidthBytes": 4782
      }
    ],
    "geography": [
      {
        "value": "India",
        "countryCode": "IN",
        "requests": 136,
        "bandwidthBytes": 11218939
      },
      {
        "value": "Singapore",
        "countryCode": "SG",
        "requests": 22,
        "bandwidthBytes": 5669799
      }
    ],
    "devices": [
      {
        "value": "Desktop",
        "requests": 139,
        "bandwidthBytes": 16644941
      },
      {
        "value": "Smartphone",
        "requests": 17,
        "bandwidthBytes": 237432
      }
    ],
    "transformations": [
      {
        "value": "n-ik_ml_thumbnail",
        "requests": 80,
        "bandwidthBytes": 868433
      }
    ],
    "images": [
      {
        "value": "https://ik.imagekit.io/your_id/photo.jpeg",
        "requests": 80,
        "bandwidthBytes": 868433
      }
    ],
    "videos": [
      {
        "value": "https://ik.imagekit.io/your_id/clip.mp4",
        "requests": 8,
        "bandwidthBytes": 6727289
      }
    ],
    "others": [
      {
        "value": "https://ik.imagekit.io/your_id/design.psd",
        "requests": 2,
        "bandwidthBytes": 1389412
      }
    ],
    "referral": [],
    "videoTransformations": [],
    "resultType": [
      {
        "value": "Miss",
        "requests": 96,
        "bandwidthBytes": 12276318
      },
      {
        "value": "Hit",
        "requests": 56,
        "bandwidthBytes": 5992387
      },
      {
        "value": "Error",
        "requests": 8,
        "bandwidthBytes": 4782
      }
    ],
    "userAgents": [
      {
        "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
        "requests": 103,
        "bandwidthBytes": 10238534
      },
      {
        "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
        "requests": 22,
        "bandwidthBytes": 5669799
      }
    ]
  },
  "topBreakdownsByBandwidth": {
    "statusCodes": [
      {
        "value": "200",
        "requests": 148,
        "bandwidthBytes": 13924675
      },
      {
        "value": "206",
        "requests": 4,
        "bandwidthBytes": 4344030
      },
      {
        "value": "404",
        "requests": 7,
        "bandwidthBytes": 4250
      }
    ],
    "formats": [
      {
        "value": "video/webm",
        "requests": 8,
        "bandwidthBytes": 6727289
      },
      {
        "value": "image/webp",
        "requests": 119,
        "bandwidthBytes": 5261379
      },
      {
        "value": "image/jpeg",
        "requests": 20,
        "bandwidthBytes": 4570132
      }
    ],
    "cache": [
      {
        "value": "Miss",
        "requests": 96,
        "bandwidthBytes": 12276318
      },
      {
        "value": "Hit",
        "requests": 56,
        "bandwidthBytes": 5992387
      },
      {
        "value": "Error",
        "requests": 8,
        "bandwidthBytes": 4782
      }
    ],
    "geography": [
      {
        "value": "India",
        "countryCode": "IN",
        "requests": 136,
        "bandwidthBytes": 11218939
      },
      {
        "value": "Singapore",
        "countryCode": "SG",
        "requests": 22,
        "bandwidthBytes": 5669799
      }
    ],
    "devices": [
      {
        "value": "Desktop",
        "requests": 139,
        "bandwidthBytes": 16644941
      },
      {
        "value": "Smartphone",
        "requests": 17,
        "bandwidthBytes": 237432
      }
    ],
    "transformations": [
      {
        "value": "n-ik_ml_thumbnail",
        "requests": 80,
        "bandwidthBytes": 868433
      }
    ],
    "images": [
      {
        "value": "https://ik.imagekit.io/your_id/photo.jpeg",
        "requests": 80,
        "bandwidthBytes": 868433
      }
    ],
    "videos": [
      {
        "value": "https://ik.imagekit.io/your_id/clip.mp4",
        "requests": 8,
        "bandwidthBytes": 6727289
      }
    ],
    "others": [
      {
        "value": "https://ik.imagekit.io/your_id/design.psd",
        "requests": 2,
        "bandwidthBytes": 1389412
      }
    ],
    "referral": [],
    "videoTransformations": [],
    "resultType": [
      {
        "value": "Miss",
        "requests": 96,
        "bandwidthBytes": 12276318
      },
      {
        "value": "Hit",
        "requests": 56,
        "bandwidthBytes": 5992387
      },
      {
        "value": "Error",
        "requests": 8,
        "bandwidthBytes": 4782
      }
    ],
    "userAgents": [
      {
        "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36",
        "requests": 103,
        "bandwidthBytes": 10238534
      },
      {
        "value": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
        "requests": 22,
        "bandwidthBytes": 5669799
      }
    ]
  }
}