> ## Documentation Index > Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt > Use this file to discover all available pages before exploring further. # List leads > Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. ## OpenAPI ````yaml /openapi/openapi.curie.json get /leads openapi: 3.0.0 info: title: Nomos API version: 2026-05-27.curie servers: - url: https://api.nomos.energy description: production security: [] tags: - name: Plans - name: Leads - name: Subscriptions - name: Customers - name: Usage - name: Prices - name: Invoices - name: Smart Meter Orders - name: Grid Fee Reductions - name: Market Partners - name: Events - name: Authentication paths: /leads: get: tags: - Leads summary: List leads description: >- Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. parameters: - schema: type: string nullable: true required: false name: cursor in: query - schema: type: integer minimum: 1 maximum: 100 default: 10 required: false name: limit in: query - schema: nullable: true description: >- **Filterable fields:** - `created_at` (date): `gte`, `lte`, `is_null` Any other field or operator returns `400`. See [Filtering Documentation](https://docs.nomos.energy/api-references/filtering) for the syntax. example: value required: false description: >- **Filterable fields:** - `created_at` (date): `gte`, `lte`, `is_null` Any other field or operator returns `400`. See [Filtering Documentation](https://docs.nomos.energy/api-references/filtering) for the syntax. name: filter[field][operator] in: query responses: '200': description: >- Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. content: application/json: schema: type: object properties: object: type: string enum: - list items: type: array items: $ref: '#/components/schemas/Lead' next_page: type: string nullable: true example: >- eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0= has_more: type: boolean default: false required: - object - items '400': description: >- The request is invalid: a field fails validation, breaks a business rule, or the body is not valid JSON. `errors` lists every problem with its field. content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' examples: Malformed filter: summary: Malformed filter value: code: BAD_REQUEST message: >- Invalid filter syntax: 'filter[created_at]'. Expected format: filter[field][operator]=value requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST Unknown filter field: summary: Unknown filter field value: code: BAD_REQUEST message: >- Unknown filter field 'created_ats'. Filterable fields: created_at. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: unrecognized_keys field: filter[created_ats][eq] message: >- Unknown filter field 'created_ats'. Filterable fields: created_at. Operator the field does not accept: summary: Operator the field does not accept value: code: BAD_REQUEST message: >- Operator 'eq' is not supported on 'created_at'. Use one of: gte, lte, is_null. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: unrecognized_keys field: filter[created_at][eq] message: >- Operator 'eq' is not supported on 'created_at'. Use one of: gte, lte, is_null. Limit out of range: $ref: '#/components/examples/400-limit-out-of-range' Invalid cursor: $ref: '#/components/examples/400-invalid-cursor' Unsupported version header: $ref: '#/components/examples/400-unsupported-version-header' '401': description: The access token is missing, expired or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' examples: No token: $ref: '#/components/examples/401-no-token' Expired token: $ref: '#/components/examples/401-expired-token' Invalid token: $ref: '#/components/examples/401-invalid-token' '403': description: The access token is valid but not allowed to use this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrForbidden' examples: Role without access: $ref: '#/components/examples/403-role-without-access' Token without scope: $ref: '#/components/examples/403-token-without-scope' Customer token without customer: $ref: '#/components/examples/403-customer-token-without-customer' '404': description: >- A resource in the path or the body does not exist or belongs to another organization, or the endpoint does not exist in the API version of your token. content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' examples: Endpoint not in your API version: summary: Endpoint not in your API version value: code: NOT_FOUND message: There is no GET /leads in API version 2025-12-01.chucky. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND '422': description: >- A query parameter, such as a filter value or a date range, is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrUnprocessableEntity' examples: Date filter without time zone: $ref: '#/components/examples/422-date-filter-without-time-zone' '500': description: >- Something went wrong on our side. Retry later, and send us the `requestId` if it persists. content: application/json: schema: $ref: '#/components/schemas/ErrInternalServerError' examples: Unexpected error: $ref: '#/components/examples/500-unexpected-error' security: - Bearer: [] components: schemas: Lead: type: object properties: object: type: string enum: - lead id: type: string description: Unique identifier for the lead example: lead_a8n8ol7yd4h0wohx824f0bui subscription: type: string nullable: true description: ID of the subscription, if the lead is converted to a subscription example: sub_a8n8ol7yd4h0wohx824f0bui subscribed_at: anyOf: - type: string - type: string format: date-time - nullable: true description: Timestamp when the lead was converted to a subscription example: '2024-03-14T12:00:00Z' link: type: string description: URL of the lead example: https://nomos.checkout.energy?id=lead_a8n8ol7yd4h0wohx824f0bui created_at: anyOf: - type: string - type: string format: date-time description: Timestamp when the lead was created example: '2024-03-14T12:00:00Z' created_by: type: string nullable: true description: Email of the user who created the lead example: john.doe@example.com last_visited_at: anyOf: - type: string - type: string format: date-time - nullable: true description: Timestamp when the lead was last visited example: '2024-03-14T12:00:00Z' metadata: type: object nullable: true additionalProperties: nullable: true description: Metadata of the lead, can be internal data example: utm_source: google utm_campaign: campaign_name user_id: '1234567890' required: - object - id - link - created_at ErrBadRequest: type: object properties: code: type: string enum: - BAD_REQUEST description: The error code related to the status code. example: BAD_REQUEST message: type: string description: A human readable message describing the issue. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: type: array items: type: object properties: code: type: string description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-enum: - invalid_type - too_big - too_small - invalid_format - not_multiple_of - unrecognized_keys - invalid_union - invalid_key - invalid_element - invalid_value - custom - unserviceable_zip - ended_subscription - duplicate_grid_reduction - missing_smart_meter - missing_module_1 - incompatible_grid_reduction - unsupported_product - unsupported_meter_order - duplicate_meter_order - unsupported_meter - out_of_period_meter_reading - unsupported_meter_reading - duplicate_meter_reading - implausible_meter_reading - duplicate_customer_email - invalid_iban - upgrade_api_version - withdrawal_not_allowed - invalid_termination_date - subscription_not_started - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' required: - code - field - message description: >- Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff. required: - code - message - requestId - docs ErrUnauthorized: type: object properties: code: type: string enum: - UNAUTHORIZED description: The error code related to the status code. example: UNAUTHORIZED message: type: string description: A human readable message describing the issue. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED required: - code - message - requestId - docs ErrForbidden: type: object properties: code: type: string enum: - FORBIDDEN description: The error code related to the status code. example: FORBIDDEN message: type: string description: A human readable message describing the issue. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/FORBIDDEN required: - code - message - requestId - docs ErrNotFound: type: object properties: code: type: string enum: - NOT_FOUND description: The error code related to the status code. example: NOT_FOUND message: type: string description: A human readable message describing the issue. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/NOT_FOUND errors: type: array items: type: object properties: code: type: string description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-enum: - invalid_type - too_big - too_small - invalid_format - not_multiple_of - unrecognized_keys - invalid_union - invalid_key - invalid_element - invalid_value - custom - unserviceable_zip - ended_subscription - duplicate_grid_reduction - missing_smart_meter - missing_module_1 - incompatible_grid_reduction - unsupported_product - unsupported_meter_order - duplicate_meter_order - unsupported_meter - out_of_period_meter_reading - unsupported_meter_reading - duplicate_meter_reading - implausible_meter_reading - duplicate_customer_email - invalid_iban - upgrade_api_version - withdrawal_not_allowed - invalid_termination_date - subscription_not_started - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' required: - code - field - message description: >- Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff. required: - code - message - requestId - docs ErrUnprocessableEntity: type: object properties: code: type: string enum: - UNPROCESSABLE_ENTITY description: The error code related to the status code. example: UNPROCESSABLE_ENTITY message: type: string description: A human readable message describing the issue. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY errors: type: array items: type: object properties: code: type: string description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-enum: - invalid_type - too_big - too_small - invalid_format - not_multiple_of - unrecognized_keys - invalid_union - invalid_key - invalid_element - invalid_value - custom - unserviceable_zip - ended_subscription - duplicate_grid_reduction - missing_smart_meter - missing_module_1 - incompatible_grid_reduction - unsupported_product - unsupported_meter_order - duplicate_meter_order - unsupported_meter - out_of_period_meter_reading - unsupported_meter_reading - duplicate_meter_reading - implausible_meter_reading - duplicate_customer_email - invalid_iban - upgrade_api_version - withdrawal_not_allowed - invalid_termination_date - subscription_not_started - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' required: - code - field - message description: >- Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff. required: - code - message - requestId - docs ErrInternalServerError: type: object properties: code: type: string enum: - INTERNAL_SERVER_ERROR description: The error code related to the status code. example: INTERNAL_SERVER_ERROR message: type: string description: A human readable message describing the issue. requestId: type: string description: The request id to be used for debugging and error reporting. example: 37a04f8f-e791-491c-81e1-86cd304649bb docs: type: string description: The docs related to the error code. example: >- https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR required: - code - message - requestId - docs examples: 400-limit-out-of-range: summary: Limit out of range value: code: BAD_REQUEST message: limit must be a whole number from 1 to 100. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: too_big field: limit message: limit must be a whole number from 1 to 100. 400-invalid-cursor: summary: Invalid cursor value: code: BAD_REQUEST message: Invalid cursor. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: invalid_format field: cursor message: Invalid cursor. 400-unsupported-version-header: summary: Unsupported version header value: code: BAD_REQUEST message: Version header 2026-01-01.foo is invalid. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST 401-no-token: summary: No token value: code: UNAUTHORIZED message: No authorization header provided. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 401-expired-token: summary: Expired token value: code: UNAUTHORIZED message: Token expired requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 401-invalid-token: summary: Invalid token value: code: UNAUTHORIZED message: Invalid or malformed token requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 403-role-without-access: summary: Role without access value: code: FORBIDDEN message: Forbidden to access this route. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 403-token-without-scope: summary: Token without scope value: code: FORBIDDEN message: 'Insufficient scope: read:* required.' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 403-customer-token-without-customer: summary: Customer token without customer value: code: FORBIDDEN message: Customer not found. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 422-date-filter-without-time-zone: summary: Date filter without time zone value: code: UNPROCESSABLE_ENTITY message: >- Date must be in ISO 8601 format with timezone (e.g., 2024-01-01T00:00:00Z) requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY errors: - code: custom field: filter[created_at][gte] message: >- Date must be in ISO 8601 format with timezone (e.g., 2024-01-01T00:00:00Z) 500-unexpected-error: summary: Unexpected error value: code: INTERNAL_SERVER_ERROR message: Internal Server Error requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.