Generect 8. Accounts API

openapi: 3.2.0
info:
  title: Generect 8. Accounts API
  description: 'Welcome to the Generect API documentation. Here we will help you integrate and use our API.


    API base url: `https://api.generect.com` — every path below is relative to this host. Newer endpoints live under `/api/v1/...`, legacy endpoints under `/api/...`; use each path exactly as documented.

    Protocol: `HTTPS`


    # Authentication


    Get your API token from the Generect app settings and send it in the `Authorization` header with the required `Token` prefix.


    Example: `Authorization: Token xxxxxxxxx`


    # Rate limits


    There is no monthly request quota. What you can run is bounded by your account balance and by the parallel-request caps on the Limits page. Pricing depends on the operation and the number of results returned, and may increase with additional data flags. For exact pricing, see each endpoint''s Pricing section or your billing settings: https://app.generect.com/settings/billing


    # Note


    _Every endpoint must include the trailing `/`. Requests without the trailing slash may fail._'
  version: 1.0.0
  contact: {}
servers:
- url: https://api.generect.com
security:
- apiKey: []
tags:
- name: 8. Accounts
  description: Account profile, usage, and transactions.
paths:
  /api/v1/accounts/me/:
    get:
      tags:
      - 8. Accounts
      summary: Get account profile
      description: Retrieve the current account profile, credit balance, monthly usage, and Preview tier eligibility.
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Account profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountMeResponse'
              example:
                data:
                  id: a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7
                  email: jordan.ellis@microsoft.com
                  name: Jordan Ellis
                  plan: Pro
                  credits:
                    balance: 5000
                    used_this_month: 1234
                    monthly_limit: 10000
                  preview_tier: true
      operationId: getApiV1AccountsMe
      x-operation-id-source: derived
  /api/v1/accounts/usage/:
    get:
      tags:
      - 8. Accounts
      summary: Get account usage
      description: Retrieve credit usage statistics and operation breakdown for an account.
      parameters:
      - name: timezone
        in: query
        required: false
        description: IANA timezone for aggregation.
        schema:
          type: string
          default: UTC
        example: Europe/Kyiv
      - name: period
        in: query
        required: false
        description: Truncation granularity for the usage series.
        schema:
          type: string
          enum:
          - day
          - week
          - month
          default: day
      - name: start_date
        in: query
        required: false
        schema:
          type: string
        example: '2026-05-01'
      - name: end_date
        in: query
        required: false
        schema:
          type: string
        example: '2026-05-31'
      - name: period_month
        in: query
        required: false
        description: Month label for the response (YYYY-MM).
        schema:
          type: string
        example: 2026-05
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Account usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
              example:
                data:
                  period: 2026-05
                  total_credits: 1234
                  breakdown:
                    search_database: 500
                    search_realtime: 200
                    enrich_database: 300
                    enrich_realtime: 100
                    email_find: 134
      operationId: getApiV1AccountsUsage
      x-operation-id-source: derived
  /api/v1/accounts/transactions/:
    get:
      tags:
      - 8. Accounts
      summary: Get account transactions
      description: 'Your billing history: every charge and top-up on the account, newest first.


        Filters combine with AND and are applied before paging. Every `__gte` / `__lte` parameter below has a `__gt` / `__lt` twin if you need to exclude the boundary itself, and `amount` also answers to `credits`, the name the response gives it.


        One thing to watch: a value we cannot read — a misspelled status, a malformed date — is dropped rather than refused, so you get a `200` with that condition quietly missing. If a filtered call returns more than you expected, check your parameter spelling first.'
      parameters:
      - name: limit
        in: query
        required: false
        description: How many transactions to return.
        schema:
          type: integer
          default: 100
      - name: offset
        in: query
        required: false
        description: How many to skip, for paging through a long history.
        schema:
          type: integer
          default: 0
      - name: created_at__gte
        in: query
        required: false
        description: Start of the period you want. Pair it with `created_at__lte` to get a single month or billing cycle.
        schema:
          type: string
          format: date-time
        example: '2026-05-01T00:00:00Z'
      - name: created_at__lte
        in: query
        required: false
        description: End of the period, included. A bare date means midnight, so use `2026-05-31T23:59:59` to keep the last day.
        schema:
          type: string
          format: date-time
        example: '2026-05-31T23:59:59Z'
      - name: status
        in: query
        required: false
        description: Settled charges are `success`. `pending` is money reserved for a request still in flight, and `error` charges were reversed — leave both out when you reconcile spend.
        schema:
          type: string
          enum:
          - pending
          - success
          - error
      - name: amount__lte
        in: query
        required: false
        description: Charges at least this large. Charges are negative, so `amount__lte=-10` finds everything that cost 10 or more.
        schema:
          type: number
        example: -10
      - name: amount__gte
        in: query
        required: false
        description: The other side of the same window — use both to isolate a band, or this one alone with a positive value to see only top-ups.
        schema:
          type: number
      - name: after_balance__lte
        in: query
        required: false
        description: Transactions that left the balance at or below this figure. Handy for finding the moment an account started running low.
        schema:
          type: number
      - name: after_balance__gte
        in: query
        required: false
        description: Transactions that left the balance at or above this figure.
        schema:
          type: number
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Account transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTransactionsResponse'
              example:
                data:
                  transactions:
                  - id: txn_f0e1d2c3-b4a5-4697-8c9d-0e1f2a3b4c5d
                    timestamp: '2026-05-15T10:30:00Z'
                    type: search_database_leads
                    credits: -25
                    details:
                      balance_type: leads_by_icp
                      status: success
      operationId: getApiV1AccountsTransactions
      x-operation-id-source: derived
  /api/v1/accounts/tokens/analytics/:
    get:
      tags:
      - 8. Accounts
      summary: Usage by token
      description: 'The same usage figures as `/accounts/usage/`, split by API token instead of totalled for the account.


        This is for platforms that hand each of their own customers a separate Generect token. You get, per token: how many requests it made, which endpoints it called, and how many of those succeeded or failed — enough to attribute cost to the customer who caused it, or to spot the one client whose integration is retrying in a loop.


        You only ever see your own tokens, never another account''s. If you do not pass dates, the report covers the last 30 days.'
      parameters:
      - name: client_id
        in: query
        required: false
        description: Restrict the report to the token carrying this client identifier — the value set when the token was created.
        schema:
          type: string
      - name: token
        in: query
        required: false
        description: Restrict the report to one exact token value.
        schema:
          type: string
      - name: start_date
        in: query
        required: false
        description: Start of the reporting window. Accepts `YYYY-MM-DD` or a full ISO timestamp. Defaults to 30 days ago.
        schema:
          type: string
        example: '2026-05-01'
      - name: end_date
        in: query
        required: false
        description: End of the reporting window, inclusive. Defaults to now. A date with no time means midnight, so `end_date=2026-05-31` stops at the very start of the 31st and that day's traffic is not counted — pass `2026-05-31T23:59:59` (or the 1st of the next month) to include it.
        schema:
          type: string
        example: '2026-05-31T23:59:59'
      - name: timezone
        in: query
        required: false
        description: 'IANA timezone used to render the `period` bounds in the response. It does not change which requests are counted: the default window is anchored to the same instant whichever zone you name. An unrecognised name is rejected with 400.'
        schema:
          type: string
          default: UTC
        example: Europe/Kyiv
      responses:
        '400':
          description: Invalid timezone or date format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Per-token usage analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTokenAnalyticsResponse'
              example:
                data:
                  period:
                    start: '2026-05-01T00:00:00'
                    end: '2026-05-31T23:59:59'
                  total_requests: 1840
                  tokens:
                  - token: 8f14e45fceea167a5a36dedd4bea2543
                    name: Acme Corp
                    client_id: acme-corp
                    is_active: true
                    created_at: '2026-04-02T09:15:00'
                    total_requests: 1200
                    by_endpoint:
                      /api/v1/search/database/leads/: 900
                      /api/v1/email/find/: 300
                    by_status:
                      2xx: 1180
                      4xx: 20
                  - token: c9f0f895fb98ab9159f51fd0297e236d
                    name: Globex
                    client_id: globex
                    is_active: false
                    created_at: '2026-04-18T14:02:00'
                    total_requests: 640
                    by_endpoint:
                      /api/v1/search/realtime/leads/: 640
                    by_status:
                      2xx: 640
      operationId: getApiV1AccountsTokensAnalytics
      x-operation-id-source: derived
components:
  responses:
    Forbidden:
      description: Authenticated, but the account/plan is not allowed to use this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 403
            detail: You do not have permission to perform this action.
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 401
            detail: Authentication credentials were not provided.
  schemas:
    AccountTokenAnalyticsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            period:
              type: object
              description: Reporting window the counts were taken over. Timestamps are ISO-8601 but carry no UTC offset when explicit `start_date` / `end_date` were supplied, so parse them leniently rather than as strict RFC 3339.
              properties:
                start:
                  type: string
                end:
                  type: string
            total_requests:
              type: integer
              description: Requests across every token in the window.
            tokens:
              type: array
              description: One entry per token owned by the account, newest token first. A token with no traffic in the window is still listed, with zero counts.
              items:
                type: object
                properties:
                  token:
                    type: string
                  name:
                    type:
                    - string
                    - 'null'
                    description: Label given to the token when it was created. `null` for a token created without one.
                  client_id:
                    type:
                    - string
                    - 'null'
                    description: End-client identifier attached to the token.
                  is_active:
                    type: boolean
                    description: Whether the token can still authenticate. A revoked token keeps its historical counts.
                  created_at:
                    type:
                    - string
                    - 'null'
                    description: ISO-8601, without a UTC offset.
                  total_requests:
                    type: integer
                  by_endpoint:
                    type: object
                    description: Request count keyed by the path that was called.
                    additionalProperties:
                      type: integer
                  by_status:
                    type: object
                    description: Request count keyed by HTTP status class, for example `2xx`, `4xx` or `5xx`.
                    additionalProperties:
                      type: integer
    AccountUsageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            period:
              type: string
              description: Reporting period the stats cover.
            total_credits:
              type: number
              description: Total credits consumed in the period.
            breakdown:
              type: object
              description: Credits consumed per operation type.
              additionalProperties:
                type: number
    Error:
      type: object
      description: Standard error envelope returned for 4xx/5xx responses.
      properties:
        status:
          type: string
          example: error
        status_code:
          type: integer
          example: 400
        detail:
          description: 'Human-readable message (string) for most errors, or a field-level validation map ({ field: [messages] }) for 400 validation errors.'
          example: Person does not exist
    AccountTransactionsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            transactions:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  type:
                    type: string
                    description: Operation that produced the transaction.
                  credits:
                    type: number
                    description: Credit delta (negative for charges).
                  details:
                    type: object
                    properties:
                      balance_type:
                        type: string
                      status:
                        type: string
    AccountMeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
            email:
              type: string
            name:
              type: string
            plan:
              type: string
            credits:
              type: object
              description: Credit balance summary.
              properties:
                balance:
                  type: number
                  description: Current credit balance.
                used_this_month:
                  type: number
                monthly_limit:
                  type: number
            preview_tier:
              type: boolean
              description: 'True while `POST /api/v1/preview/leads/` is free for this account — that is, once total spend in the current calendar month reaches $2,000. Resets on the 1st. Not an access flag: permission to call the Preview endpoints is granted separately.'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use the required Token prefix. Example: Authorization: Token xxxxxxxxx'