Skip to main content
The Residential Ledger object represents a record of residential data usage or allocation in the Byteful system. It serves as a complete audit trail that tracks all changes to the residential data pool associated with a customer account, including daily usage consumption, top-ups, service purchases, and administrative adjustments.

​
Key Attributes

AttributeTypeDescription
residential_ledger_idstringUnique identifier for the ledger entry
residential_ledger_bytesintegerAmount of data in bytes associated with this ledger entry
residential_ledger_requestsintegerNumber of requests associated with this ledger entry
residential_ledger_period_datestringThe date this ledger entry is associated with
residential_ledger_reasonstringReason for the ledger entry (e.g., “usage”, “top_up”, “service_purchase”)
service_idstringID of the related service if applicable
service_adjustment_idintegerID of the related service adjustment if applicable
residential_ledger_creation_datetimedatetimeWhen the ledger entry was created
residential_ledger_last_update_datetimedatetimeWhen the ledger entry was last updated

​
Object Relationships

The Residential Ledger object is connected to several other objects in the Byteful API:
  • Customer: Each residential ledger entry belongs to a customer account
  • Service: Entries may be associated with a residential service (e.g., when purchasing additional data)
  • Service Adjustment: Entries may be linked to service adjustments (e.g., refunds or manual adjustments)
  • Proxy User: While not directly linked, proxy users consume data which creates ledger entries
EndpointDescription
GET /public/user/residential_ledger/retrieve/{residential_ledger_id}Retrieve a specific residential ledger entry
GET /public/user/residential_ledger/searchSearch residential ledger entries with filters
GET /public/user/residential/summaryGet a summary of residential data status

​
Example Response

{
  "data": {
    "customer_id": 1955,
    "residential_ledger_bytes": 128290101,
    "residential_ledger_creation_datetime": "2023-04-01 12:00:00",
    "residential_ledger_id": "123e4567-e89b-12d3-a456-426614174000",
    "residential_ledger_last_update_datetime": "2023-04-02 12:00:00",
    "residential_ledger_period_date": "2023-10-01",
    "residential_ledger_reason": "top_up",
    "residential_ledger_requests": 1244,
    "service_adjustment_id": 10,
    "service_id": "API-1234-5678"
  },
  "message": "Residential Ledger successfully retrieved."
}

​
Ledger Entry Types

Residential ledger entries have various reason types that indicate different data changes:
ReasonDescription
usageDaily decrements to the data pool from proxy usage
top_upIncrements from purchasing additional data
adjustmentManual adjustments (positive or negative) made by administrators

​
Usage Notes

  • The residential ledger is maintained at the account data pool level, not per proxy
  • Usage entries are aggregated daily, providing a day-by-day audit trail of data consumption
  • Entries with positive residential_ledger_bytes values add to your data pool (top-ups, purchases)
  • Entries with negative residential_ledger_bytes values subtract from your data pool (usage)
  • The residential_ledger_period_date field indicates the specific day when usage occurred or changes were made
  • Unlike datacenter and ISP proxies, residential proxies operate on a data-based billing model
  • There is no automatic expiration for residential data - it remains in your account until consumed
  • For real-time data status, use the /residential/summary endpoint