> ## Documentation Index > Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt > Use this file to discover all available pages before exploring further. # Total invoice spend per supplier, recipient or month > Groups the invoices matching the listInvoices filters by supplier, recipient or issue month and totals their spend, for example the top suppliers by spend over a period (issued_from and issued_through) or one supplier's spend per month (supplier_ids, group_by=month). Totals are the sum of the invoice amounts; credit notes reduce spend. In organization-currency totals, an invoice without an exchange rate for its date adds nothing, while invoice_count still counts it. Pass a group's key to supplier_ids or recipient_ids, or a month to issued_from and issued_through, to list its invoices. ## OpenAPI ````yaml /openapi.json get /v1/invoices/groups openapi: 3.1.0 info: title: Watchdog API version: 1.0.0 description: >- The Watchdog API is served from https://api.watchdog.no. Request bodies are limited to 2 MiB unless an endpoint says otherwise. Files are uploaded directly to storage, not through the API. servers: - url: https://api.watchdog.no description: Watchdog API security: [] paths: /v1/invoices/groups: get: tags: - Invoices summary: Total invoice spend per supplier, recipient or month description: >- Groups the invoices matching the listInvoices filters by supplier, recipient or issue month and totals their spend, for example the top suppliers by spend over a period (issued_from and issued_through) or one supplier's spend per month (supplier_ids, group_by=month). Totals are the sum of the invoice amounts; credit notes reduce spend. In organization-currency totals, an invoice without an exchange rate for its date adds nothing, while invoice_count still counts it. Pass a group's key to supplier_ids or recipient_ids, or a month to issued_from and issued_through, to list its invoices. operationId: listInvoiceGroups parameters: - name: X-Organization-Id in: header required: false schema: type: string description: >- The organization to act in. Required for personal API keys; list the organizations you can access with GET /v1/organizations. - name: fields in: query required: false schema: type: string description: >- Return only these fields of each row, comma-separated; use dots for nested fields, such as resource.id. key is always returned. Fields: group_by, key, resource, invoice_count, organization_currency, currencies. - schema: type: string enum: - 'true' - 'false' description: >- Only records matched by the filters of teams you belong to. Teams combine with OR; other filters combine with AND. Cannot be combined with team_ids. required: false description: >- Only records matched by the filters of teams you belong to. Teams combine with OR; other filters combine with AND. Cannot be combined with team_ids. name: mine in: query - schema: type: string description: >- Only records matched by the filters of these teams: at most 50, comma-separated in a query string or an array in a JSON body. Teams combine with OR. Unknown teams return 404. required: false description: >- Only records matched by the filters of these teams: at most 50, comma-separated in a query string or an array in a JSON body. Teams combine with OR. Unknown teams return 404. name: team_ids in: query - schema: type: string minLength: 1 maxLength: 200 description: >- Case-insensitive match on invoice number, title, or supplier or recipient name (as printed on the invoice or as currently named). Eight or more digits, spaces ignored, also match a printed organization number. Fewer than three characters match the start of the invoice number. required: false description: >- Case-insensitive match on invoice number, title, or supplier or recipient name (as printed on the invoice or as currently named). Eight or more digits, spaces ignored, also match a printed organization number. Fewer than three characters match the start of the invoice number. name: search in: query - schema: type: string minLength: 1 maxLength: 200 description: >- Case-insensitive match on invoice number. Fewer than three characters match its start. required: false description: >- Case-insensitive match on invoice number. Fewer than three characters match its start. name: invoice_number in: query - schema: type: string description: >- Supplier IDs, comma-separated (maximum 50). Use null for invoices without a supplier. required: false description: >- Supplier IDs, comma-separated (maximum 50). Use null for invoices without a supplier. name: supplier_ids in: query - schema: type: string description: >- Recipient IDs, comma-separated (maximum 50). Use null for invoices without a recipient. required: false description: >- Recipient IDs, comma-separated (maximum 50). Use null for invoices without a recipient. name: recipient_ids in: query - schema: type: string description: >- Categories, comma-separated: invoice, credit_note, self_billed_invoice. required: false description: >- Categories, comma-separated: invoice, credit_note, self_billed_invoice. name: categories in: query - schema: type: string description: >- Currency codes, comma-separated (maximum 50). Use null for unknown currency, for example NOK,EUR,null. required: false description: >- Currency codes, comma-separated (maximum 50). Use null for unknown currency, for example NOK,EUR,null. name: currency_codes in: query - schema: type: string enum: - and - or default: and description: >- and requires every column filter to match; or requires at least one. Search, agreement_ids, deleted and team filters always apply. required: false description: >- and requires every column filter to match; or requires at least one. Search, agreement_ids, deleted and team filters always apply. name: join_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How supplier_ids applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How supplier_ids applies: is matches any listed value; is_not excludes all listed values. name: supplier_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How recipient_ids applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How recipient_ids applies: is matches any listed value; is_not excludes all listed values. name: recipient_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How categories applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How categories applies: is matches any listed value; is_not excludes all listed values. name: category_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How currency_codes applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How currency_codes applies: is matches any listed value; is_not excludes all listed values. name: currency_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How confidence_levels applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How confidence_levels applies: is matches any listed value; is_not excludes all listed values. name: confidence_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How check_statuses applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How check_statuses applies: is matches any listed value; is_not excludes all listed values. name: check_status_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How alert_statuses applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How alert_statuses applies: is matches any listed value; is_not excludes all listed values. name: alert_status_operator in: query - schema: type: string enum: - is - is_not default: is description: >- How display_statuses applies: is matches any listed value; is_not excludes all listed values. required: false description: >- How display_statuses applies: is matches any listed value; is_not excludes all listed values. name: display_status_operator in: query - schema: type: string description: >- Alert status, comma-separated: credited (covered by credit notes), checking (a check is running), has_issues (open alerts), clean (checked, no open alerts), not_checked. required: false description: >- Alert status, comma-separated: credited (covered by credit notes), checking (a check is running), has_issues (open alerts), clean (checked, no open alerts), not_checked. name: alert_statuses in: query - schema: type: string description: >- Like alert_statuses, but splits credited into resolved_by_credit_note (alerts were found first) and pre_empted_by_credit_note (no alerts were found). Comma-separated: not_checked, checking, has_issues, clean, resolved_by_credit_note, pre_empted_by_credit_note. required: false description: >- Like alert_statuses, but splits credited into resolved_by_credit_note (alerts were found first) and pre_empted_by_credit_note (no alerts were found). Comma-separated: not_checked, checking, has_issues, clean, resolved_by_credit_note, pre_empted_by_credit_note. name: display_statuses in: query - schema: type: string description: 'Extraction confidence, comma-separated: high, mid, low or unknown.' required: false description: 'Extraction confidence, comma-separated: high, mid, low or unknown.' name: confidence_levels in: query - schema: type: string description: >- Check status, comma-separated: completed (every matched agreement checked), incomplete (some checks missing, failed or outdated), checking, not_checked, or not_checkable (credit notes, invoices with a matched credit note, invoices without a document). required: false description: >- Check status, comma-separated: completed (every matched agreement checked), incomplete (some checks missing, failed or outdated), checking, not_checked, or not_checkable (credit notes, invoices with a matched credit note, invoices without a document). name: check_statuses in: query - schema: type: string enum: - 'true' - 'false' description: >- true selects invoices linked to a credit note, and credit notes linked to an invoice; false selects those without. required: false description: >- true selects invoices linked to a credit note, and credit notes linked to an invoice; false selects those without. name: has_recorded_match in: query - schema: type: string enum: - invoice - selected_agreements default: invoice description: >- invoice covers all of the invoice's checks and alerts; selected_agreements covers only the agreements in agreement_ids (required). required: false description: >- invoice covers all of the invoice's checks and alerts; selected_agreements covers only the agreements in agreement_ids (required). name: alert_scope in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Earliest issue date (YYYY-MM-DD), inclusive. required: false description: Earliest issue date (YYYY-MM-DD), inclusive. name: issued_from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Latest issue date (YYYY-MM-DD), inclusive. required: false description: Latest issue date (YYYY-MM-DD), inclusive. name: issued_through in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Earliest due date (YYYY-MM-DD), inclusive. required: false description: Earliest due date (YYYY-MM-DD), inclusive. name: due_from in: query - schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Latest due date (YYYY-MM-DD), inclusive. required: false description: Latest due date (YYYY-MM-DD), inclusive. name: due_through in: query - schema: type: string enum: - 'true' - 'false' description: Whether the amounts add up (see amounts.valid). required: false description: Whether the amounts add up (see amounts.valid). name: financially_valid in: query - schema: type: string enum: - 'true' - 'false' description: Whether a person has confirmed the extracted data. required: false description: Whether a person has confirmed the extracted data. name: extraction_confirmed in: query - schema: type: string enum: - 'true' - 'false' description: Whether review is recommended (see review.recommended). required: false description: Whether review is recommended (see review.recommended). name: review_recommended in: query - schema: type: string description: >- Agreement IDs, comma-separated (maximum 50). Selects invoices matched to any of them. required: false description: >- Agreement IDs, comma-separated (maximum 50). Selects invoices matched to any of them. name: agreement_ids in: query - schema: type: string enum: - 'true' - 'false' description: Whether the invoice is matched to at least one agreement. required: false description: Whether the invoice is matched to at least one agreement. name: has_agreement_match in: query - schema: type: string enum: - 'true' - 'false' description: Whether the invoice has open (pending or claimed) alerts. required: false description: Whether the invoice has open (pending or claimed) alerts. name: has_open_alerts in: query - schema: type: string enum: - 'true' - 'false' default: 'false' description: true lists only soft-deleted invoices. Defaults to false. required: false description: true lists only soft-deleted invoices. Defaults to false. name: deleted in: query - schema: type: integer minimum: 1 maximum: 1000 default: 50 description: Maximum number of results per page. required: false description: Maximum number of results per page. name: limit in: query - schema: type: string maxLength: 4096 description: >- Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page. required: false description: >- Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page. name: cursor in: query - schema: type: string enum: - supplier - recipient - month required: true name: group_by in: query - schema: type: string enum: - total_amount_excluding_vat - total_amount_including_vat - invoice_count - key default: total_amount_excluding_vat description: >- Totals sort by their organization-currency value. key sorts by the group key, so months in calendar order. required: false description: >- Totals sort by their organization-currency value. key sorts by the group key, so months in calendar order. name: sort in: query - schema: type: string enum: - asc - desc default: desc required: false name: direction in: query responses: '200': description: A page of groups with invoice counts and spend. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/InvoiceGroup' maxItems: 1000 next_cursor: type: - string - 'null' required: - data - next_cursor '400': description: >- The request is invalid. details lists up to 20 field errors. Request bodies are limited to 2 MiB. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: '#/components/schemas/Error_validation_error' example: error: code: validation_error message: >- The request is invalid. details lists up to 20 field errors. Request bodies are limited to 2 MiB. request_id: req_example '401': description: The bearer token is missing or invalid. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. WWW-Authenticate: schema: type: string required: false description: Bearer authentication challenge, when supplied. content: application/json: schema: $ref: '#/components/schemas/Error_invalid_token' example: error: code: invalid_token message: The bearer token is missing or invalid. request_id: req_example '403': description: >- Access denied. The error code says why: forbidden, token_disabled, organization_required, insufficient_role or mfa_required. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: >- #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required example: error: code: forbidden message: >- Access denied. The error code says why: forbidden, token_disabled, organization_required, insufficient_role or mfa_required. request_id: req_example '404': description: The resource does not exist in the current organization. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: '#/components/schemas/Error_not_found' example: error: code: not_found message: The resource does not exist in the current organization. request_id: req_example '409': description: >- One or more selected teams have invalid saved filter rules. Update the team filters before retrying. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: '#/components/schemas/Error_conflict' example: error: code: conflict message: >- One or more selected teams have invalid saved filter rules. Update the team filters before retrying. request_id: req_example '422': description: >- More than 1,000 invoices match search or invoice_number. Narrow the search or use other filters. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: '#/components/schemas/Error_search_too_broad' example: error: code: search_too_broad message: >- More than 1,000 invoices match search or invoice_number. Narrow the search or use other filters. request_id: req_example '429': description: Too many requests. Wait for the Retry-After delay before retrying. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_rate_limit_exceeded' example: error: code: rate_limit_exceeded message: >- Too many requests. Wait for the Retry-After delay before retrying. request_id: req_example '500': description: >- Unexpected server failure. Include the request ID when contacting support. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. content: application/json: schema: $ref: '#/components/schemas/Error_internal_error' example: error: code: internal_error message: >- Unexpected server failure. Include the request ID when contacting support. request_id: req_example '503': description: >- Temporarily unavailable. Retry after the Retry-After delay, when provided. headers: X-Request-Id: schema: type: string required: true description: >- Request ID, also included in error bodies. Include it when contacting support. Cache-Control: schema: type: string enum: - private, no-store - private, no-store, no-transform required: false description: API responses are private and must not be cached. X-RateLimit-Limit: schema: type: string example: '500' required: false description: >- Requests allowed per minute for this credential, or failed API key attempts allowed per minute from this IP address. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_service_unavailable' example: error: code: service_unavailable message: >- Temporarily unavailable. Retry after the Retry-After delay, when provided. request_id: req_example security: - ApiKeyBearer: [] components: schemas: InvoiceGroup: type: object properties: group_by: type: string enum: - supplier - recipient - month key: type: - string - 'null' description: >- The group's filter value: a supplier or recipient ID (supplier_ids, recipient_ids), or the issue month as YYYY-MM (issued_from and issued_through). Null means no supplier, recipient or issue date. resource: type: - object - 'null' properties: id: type: string format: uuid name: type: - string - 'null' required: - id - name description: >- The group's supplier or recipient with its current name. Null for month groups. invoice_count: type: integer organization_currency: type: object properties: currency_code: type: string total_amount_excluding_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Spend: the known totals excluding VAT; credit notes reduce it. Sort by it to rank groups. example: '1250.00' total_amount_including_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal as a string. Parse it as a decimal, not a floating-point number. example: '1250.00' required: - currency_code - total_amount_excluding_vat - total_amount_including_vat description: >- Totals converted to the organization currency at each invoice's date, rounded to cents. currencies: type: array items: type: object properties: currency_code: type: - string - 'null' invoice_count: type: integer total_amount_excluding_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal as a string. Parse it as a decimal, not a floating-point number. example: '1250.00' total_amount_including_vat: type: string maxLength: 100 pattern: ^-?\d+(?:\.\d+)?$ description: >- Exact decimal as a string. Parse it as a decimal, not a floating-point number. example: '1250.00' required: - currency_code - invoice_count - total_amount_excluding_vat - total_amount_including_vat required: - group_by - key - resource - invoice_count - organization_currency - currencies Error_validation_error: type: object properties: error: type: object properties: code: type: string enum: - validation_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_invalid_token: type: object properties: error: type: object properties: code: type: string enum: - invalid_token message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required: type: object properties: error: type: object properties: code: type: string enum: - forbidden - token_disabled - organization_required - insufficient_role - mfa_required message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_not_found: type: object properties: error: type: object properties: code: type: string enum: - not_found message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_conflict: type: object properties: error: type: object properties: code: type: string enum: - conflict message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_search_too_broad: type: object properties: error: type: object properties: code: type: string enum: - search_too_broad message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_rate_limit_exceeded: type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_internal_error: type: object properties: error: type: object properties: code: type: string enum: - internal_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_service_unavailable: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error securitySchemes: ApiKeyBearer: type: http scheme: bearer description: >- Personal API key sent as a bearer token, together with X-Organization-Id. The key must have at least the access level the endpoint requires (read, write or admin). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.