> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Events

> List usage events for your organization. Filter by customer, feature, or time range.

export const DynamicResponseExample = ({json, statusCode = "200"}) => {
  const toCamelCase = str => {
    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
  };
  const convertKeysToCamelCase = obj => {
    if (Array.isArray(obj)) {
      return obj.map(item => convertKeysToCamelCase(item));
    }
    if (obj !== null && typeof obj === "object") {
      return Object.keys(obj).reduce((acc, key) => {
        const camelKey = toCamelCase(key);
        acc[camelKey] = convertKeysToCamelCase(obj[key]);
        return acc;
      }, {});
    }
    return obj;
  };
  const [isTypeScript, setIsTypeScript] = useState(() => {
    if (typeof window !== "undefined") {
      try {
        const lang = localStorage.getItem("code");
        return JSON.parse(lang) === "typescript";
      } catch {
        return true;
      }
    }
    return true;
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      if (event.detail?.key === "code") {
        try {
          const value = JSON.parse(event.detail.value);
          setIsTypeScript(value === "typescript");
        } catch {}
      }
    };
    const pollInterval = setInterval(() => {
      try {
        const lang = localStorage.getItem("code");
        const value = JSON.parse(lang);
        setIsTypeScript(value === "typescript");
      } catch {}
    }, 300);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, []);
  const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
  const snakeCaseString = JSON.stringify(json, null, 2);
  const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
  return <ResponseExample>
			{isTypeScript ? <CodeBlock language="json" filename={statusCode}>
					{camelCaseString}
				</CodeBlock> : <CodeBlock language="json" filename={statusCode}>
					{snakeCaseString}
				</CodeBlock>}
		</ResponseExample>;
};

export const DynamicResponseField = ({children, name, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedName = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(name) : name;
    } catch {
      return name;
    }
  }, [name, lang]);
  return <ResponseField name={resolvedName} {...props}>
			{children}
		</ResponseField>;
};

export const DynamicParamField = ({children, body, path, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedBody = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(body) : body;
    } catch {
      return body;
    }
  }, [body, lang]);
  const resolvedPath = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(path) : path;
    } catch {
      return path;
    }
  }, [path, lang]);
  return <ParamField body={resolvedBody} path={resolvedPath} {...props}>
			{children}
		</ParamField>;
};

### Body Parameters

<DynamicParamField body="start_cursor" type="string">
  Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
</DynamicParamField>

<DynamicParamField body="limit" type="integer">
  Number of items to return. Default 50, hard ceiling 5000.
</DynamicParamField>

<DynamicParamField body="customer_id" type="string">
  Filter events by customer ID
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  Filter events by entity ID (e.g., per-seat or per-resource)
</DynamicParamField>

<DynamicParamField body="feature_id" type="string">
  Filter by specific feature ID(s)
</DynamicParamField>

<DynamicParamField body="custom_range" type="object">
  Filter events by time range

  <Expandable title="properties">
    <DynamicParamField body="start" type="number">
      Filter events after this timestamp (epoch milliseconds)
    </DynamicParamField>

    <DynamicParamField body="end" type="number">
      Filter events before this timestamp (epoch milliseconds)
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

### Response

<DynamicResponseField name="list" type="object[]">
  Items for current page.

  <Expandable title="properties">
    <DynamicResponseField name="id" type="string">
      Event ID (KSUID)
    </DynamicResponseField>

    <DynamicResponseField name="timestamp" type="number">
      Event timestamp (epoch milliseconds)
    </DynamicResponseField>

    <DynamicResponseField name="feature_id" type="string">
      ID of the feature that the event belongs to
    </DynamicResponseField>

    <DynamicResponseField name="customer_id" type="string">
      Customer identifier
    </DynamicResponseField>

    <DynamicResponseField name="value" type="number">
      Event value/count
    </DynamicResponseField>

    <DynamicResponseField name="properties" type="object">
      Event properties (JSON)
    </DynamicResponseField>

    <DynamicResponseField name="deductions" type="object[] | null">
      Per-balance breakdown of what this event deducted. Null for events ingested before deductions were tracked; an empty array means the event was accepted but no balance moved.

      <Expandable title="properties">
        <DynamicResponseField name="balance_id" type="string">
          ID of the underlying balance row that was deducted from (customer\_entitlement or rollover).
        </DynamicResponseField>

        <DynamicResponseField name="feature_id" type="string">
          The feature this balance belongs to.
        </DynamicResponseField>

        <DynamicResponseField name="plan_id" type="string | null">
          ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple).
        </DynamicResponseField>

        <DynamicResponseField name="reset" type="object | null">
          Reset configuration for the balance this deduction came from, or null if the balance doesn't reset.

          <Expandable title="properties">
            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
            </DynamicResponseField>

            <DynamicResponseField name="interval_count" type="number">
              Number of intervals between resets (eg. 2 for bi-monthly).
            </DynamicResponseField>

            <DynamicResponseField name="resets_at" type="number | null">
              Timestamp when the balance will next reset.
            </DynamicResponseField>
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="value" type="number">
          Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value).
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="next_cursor" type="string | null">
  Opaque cursor for the next page. Null when there are no more results.
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "list": [
      {
        "id": "evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg",
        "timestamp": 1765958215459,
        "feature_id": "credits",
        "customer_id": "0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx",
        "value": 30,
        "properties": {},
        "deductions": [
          {
            "balance_id": "cus_ent_3DdSDtFBlvDbjyUuJeUIbQlyN12",
            "feature_id": "credits",
            "plan_id": "pro",
            "reset": {
              "interval": "month",
              "resets_at": 1765958215459
            },
            "value": 30
          }
        ]
      },
      {
        "id": "evt_36xmHxxjAkqxufDf9yHAPNfRrLM",
        "timestamp": 1765956512057,
        "feature_id": "credits",
        "customer_id": "0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx",
        "value": 49,
        "properties": {},
        "deductions": null
      }
    ],
    "next_cursor": "eyJ2IjowLCJpZCI6ImV2dF8zNnhtSHh4akFrcXh1ZkRmOXlIQVBOZlJyTE0iLCJ0IjoxNzY1OTU2NTEyMDU3fQ"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/events.list
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.3.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/events.list:
    post:
      tags:
        - events
      description: >-
        List usage events for your organization. Filter by customer, feature, or
        time range.
      operationId: listEvents
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.3.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_cursor:
                  type: string
                  default: ''
                  description: >-
                    Opaque pagination cursor. Empty string (default) requests
                    the first page; use next_cursor from a prior response for
                    subsequent pages.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 5000
                  default: 50
                  description: Number of items to return. Default 50, hard ceiling 5000.
                customer_id:
                  type: string
                  description: Filter events by customer ID
                entity_id:
                  type: string
                  minLength: 1
                  description: Filter events by entity ID (e.g., per-seat or per-resource)
                feature_id:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: array
                      items:
                        type: string
                        minLength: 1
                  description: Filter by specific feature ID(s)
                custom_range:
                  type: object
                  properties:
                    start:
                      type: number
                      description: Filter events after this timestamp (epoch milliseconds)
                    end:
                      type: number
                      description: Filter events before this timestamp (epoch milliseconds)
                  description: Filter events by time range
              title: EventsListParams
              examples:
                - start_cursor: ''
                  customer_id: cus_123
                  limit: 50
                - start_cursor: ''
                  feature_id: api_calls
                  custom_range:
                    start: 1704067200000
                    end: 1706745600000
            example:
              start_cursor: ''
              customer_id: cus_123
              limit: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Event ID (KSUID)
                        timestamp:
                          type: number
                          description: Event timestamp (epoch milliseconds)
                        feature_id:
                          type: string
                          description: ID of the feature that the event belongs to
                        customer_id:
                          type: string
                          description: Customer identifier
                        value:
                          type: number
                          description: Event value/count
                        properties:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties: {}
                          description: Event properties (JSON)
                        deductions:
                          anyOf:
                            - type: array
                              items:
                                type: object
                                properties:
                                  balance_id:
                                    type: string
                                    description: >-
                                      ID of the underlying balance row that was
                                      deducted from (customer_entitlement or
                                      rollover).
                                  feature_id:
                                    type: string
                                    description: The feature this balance belongs to.
                                  plan_id:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                    description: >-
                                      ID of the plan/product this balance
                                      belongs to. Null when the balance can't be
                                      attributed to a single plan (e.g. it spans
                                      multiple).
                                  reset:
                                    anyOf:
                                      - type: object
                                        properties:
                                          interval:
                                            anyOf:
                                              - enum:
                                                  - one_off
                                                  - minute
                                                  - hour
                                                  - day
                                                  - week
                                                  - month
                                                  - quarter
                                                  - semi_annual
                                                  - year
                                                type: string
                                              - const: multiple
                                            description: >-
                                              The reset interval (hour, day, week,
                                              month, etc.) or 'multiple' if combined
                                              from different intervals.
                                          interval_count:
                                            type: number
                                            description: >-
                                              Number of intervals between resets (eg.
                                              2 for bi-monthly).
                                          resets_at:
                                            anyOf:
                                              - type: number
                                              - type: 'null'
                                            description: >-
                                              Timestamp when the balance will next
                                              reset.
                                        required:
                                          - interval
                                          - resets_at
                                      - type: 'null'
                                    description: >-
                                      Reset configuration for the balance this
                                      deduction came from, or null if the
                                      balance doesn't reset.
                                  value:
                                    type: number
                                    description: >-
                                      Amount deducted from this balance.
                                      Positive when usage was consumed, negative
                                      when credit was restored (e.g. a refund
                                      via negative track value).
                                required:
                                  - balance_id
                                  - feature_id
                                  - plan_id
                                  - reset
                                  - value
                            - type: 'null'
                          description: >-
                            Per-balance breakdown of what this event deducted.
                            Null for events ingested before deductions were
                            tracked; an empty array means the event was accepted
                            but no balance moved.
                      required:
                        - id
                        - timestamp
                        - feature_id
                        - customer_id
                        - value
                        - properties
                        - deductions
                    description: Items for current page.
                  next_cursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Opaque cursor for the next page. Null when there are no
                      more results.
                required:
                  - list
                  - next_cursor
                examples:
                  - list:
                      - id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg
                        timestamp: 1765958215459
                        feature_id: credits
                        customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
                        value: 30
                        properties: {}
                        deductions:
                          - balance_id: cus_ent_3DdSDtFBlvDbjyUuJeUIbQlyN12
                            feature_id: credits
                            plan_id: pro
                            reset:
                              interval: month
                              resets_at: 1765958215459
                            value: 30
                      - id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM
                        timestamp: 1765956512057
                        feature_id: credits
                        customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
                        value: 49
                        properties: {}
                        deductions: null
                    next_cursor: >-
                      eyJ2IjowLCJpZCI6ImV2dF8zNnhtSHh4akFrcXh1ZkRmOXlIQVBOZlJyTE0iLCJ0IjoxNzY1OTU2NTEyMDU3fQ
              example:
                list:
                  - id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg
                    timestamp: 1765958215459
                    feature_id: credits
                    customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
                    value: 30
                    properties: {}
                    deductions:
                      - balance_id: cus_ent_3DdSDtFBlvDbjyUuJeUIbQlyN12
                        feature_id: credits
                        plan_id: pro
                        reset:
                          interval: month
                          resets_at: 1765958215459
                        value: 30
                  - id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM
                    timestamp: 1765956512057
                    feature_id: credits
                    customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx
                    value: 49
                    properties: {}
                    deductions: null
                next_cursor: >-
                  eyJ2IjowLCJpZCI6ImV2dF8zNnhtSHh4akFrcXh1ZkRmOXlIQVBOZlJyTE0iLCJ0IjoxNzY1OTU2NTEyMDU3fQ
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.events.list({
              customerId: "cus_123",
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.events.list(
                start_cursor="",
                limit=50,
                customer_id="cus_123",
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````