1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

Retrieve monthly activity counts, credits consumed, and daily breakdowns for the workspace associated with your API key. Usage reports activities and credit consumption; Billing reports balances, money, payment methods, and invoices.

GET /v1/usage

Authentication

All requests require a workspace API key:

Authorization: Bearer 1eye_live_xxxxxxxxx

The examples use $API_KEY for your API key. The key determines the workspace; you do not supply a workspace ID. See Authentication.

Query parameter

Parameter	Type	Description
`month`	string	Optional reporting month in `YYYY-MM` format. Defaults to the current calendar month.

No other query parameters, pagination, or sorting are supported.

Request

Current month:

curl "https://api.1eye.ai/v1/usage" \
  -H "Authorization: Bearer $API_KEY"

Historical month:

curl "https://api.1eye.ai/v1/usage?month=2026-09" \
  -H "Authorization: Bearer $API_KEY"

Response

200 OK — returns the Usage object directly. The complete fictional example below is a snapshot taken on October 1, 2026, so its current-month daily array contains one applicable date. The example pricing and quantities do not prescribe workspace defaults.

{
  "client_id": "wor_123456789012345678",
  "month": "2026-10",
  "available_months": {
    "from": "2026-04",
    "to": "2026-10"
  },
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "monthly": {
    "credits_consumed": 145,
    "breakdown": {
      "buyer": {
        "count": 50,
        "credits_consumed": 100
      },
      "signal": {
        "count": 15,
        "credits_consumed": 15
      },
      "email": {
        "count": 10,
        "credits_consumed": 20
      },
      "phone": {
        "count": 2,
        "credits_consumed": 10
      }
    }
  },
  "daily": [
    {
      "date": "2026-10-01",
      "credits_consumed": 145,
      "breakdown": {
        "buyer": {
          "count": 50,
          "credits_consumed": 100
        },
        "signal": {
          "count": 15,
          "credits_consumed": 15
        },
        "email": {
          "count": 10,
          "credits_consumed": 20
        },
        "phone": {
          "count": 2,
          "credits_consumed": 10
        }
      }
    }
  ]
}

Usage fields

Field	Type	Description
`client_id`	string	Workspace ID.
`month`	string	Selected reporting month, `YYYY-MM`.
`available_months`	object	Inclusive supported reporting range: `from` and `to`.
`credit_costs`	object	Current configured credits per `buyer`, `signal`, `email`, and `phone` activity.
`monthly`	object	Selected month’s authoritative total and activity breakdown.
`daily`	array	Daily totals and activity breakdowns in ascending date order.

Activity breakdown

Both monthly.breakdown and every daily breakdown contain buyer, signal, email, and phone. Each category has count and credits_consumed.

Category	Meaning
`buyer`	Billable Buyer activity.
`signal`	Billable Signal activity.
`email`	Billable Email activity.
`phone`	Billable Phone activity.

count measures the activity quantity. credits_consumed records credits actually charged for that category. date is the reporting-calendar date in YYYY-MM-DD format.

Discover available history

Read available_months.from and .to before requesting historical months. Both are inclusive. Every successful response includes the range, even when requesting a historical month. A supported month with no usage returns confirmed zero totals and the full daily date series. A month outside the range, or a future month, returns 400 rather than an invented zero-usage report. Invalid formats include 2026-1, 2026-13, and 2026-10-01.

Daily coverage

Historical months include every date in that calendar month, including weekends and zero-usage days.
The current month includes dates from the first day through the current reporting date. Today’s usage can increase as activity is processed.
Future dates are excluded.
Billing and Usage use the same authoritative calendar boundaries; the caller’s local timezone does not redefine them.

Pricing and historical consumption

credit_costs is the current configuration and matches Billing. Historical credits_consumed reflects the prices charged when the activities occurred. Do not recalculate historical consumption by multiplying counts by today’s costs. For example, a historical month with 94 Buyers charged at 10 credits and 117 Signals charged at 1 credit consumed 1,057 credits, even if the current Buyer cost is now 2 credits.

Unavailable historical categories

When an older category cannot be reliably reconstructed, its two values are null together:

{
  "count": null,
  "credits_consumed": null
}

This category object means unavailable reporting, not zero usage. A confirmed zero category uses numeric zeros. Authoritative monthly and daily credit totals remain available even when an older category breakdown is unavailable. When every category is known, category credits sum to the containing total and daily totals sum to monthly usage. Credit purchases, grants, payment amounts, balances, and invoices belong to Billing and are not counted as usage activity.

Errors

Status	Error code	Description
400	`invalid_parameter`	A request field or query parameter is invalid.
401	`authentication_error`	The API key is missing, invalid, or revoked.
403	`permission_denied`	The key does not have permission for this operation.
429	`rate_limit_exceeded`	The workspace API rate limit was exceeded.
500	`internal_error`	An unexpected server error occurred.
503	`service_unavailable`	The service is temporarily unavailable.

Errors use the standard error envelope. Use request_id when contacting support.

Unsupported month error

{
  "error": {
    "code": "invalid_parameter",
    "message": "Usage data is available from 2026-04 through 2026-10.",
    "param": "month",
    "request_id": "req_123456789012345678"
  }
}

The dates in an actual error describe the workspace’s current available range.

Get Started

Buyers

Signals

Target Lists

Destinations

Knowledge Base

Workspace

Usage

Authentication

Query parameter

Request

Response

Usage fields

Activity breakdown

Discover available history

Daily coverage

Pricing and historical consumption

Unavailable historical categories

Errors

Unsupported month error

​Authentication

​Query parameter

​Request

​Response

​Usage fields

​Activity breakdown

​Discover available history

​Daily coverage

​Pricing and historical consumption

​Unavailable historical categories

​Errors

​Unsupported month error

Authentication

Query parameter

Request

Response

Usage fields

Activity breakdown

Discover available history

Daily coverage

Pricing and historical consumption

Unavailable historical categories

Errors

Unsupported month error