---
title: "List Forms"
method: GET
path: "/forms"
tags: ["Forms"]
---

# List Forms

`GET /forms`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/forms`
- Auth: HTTP bearer

List and search the org's lead-capture forms.

Use ``search`` to find a specific form by name (e.g. "discovery"). Each
item carries the ``source_id`` and ``form_key`` needed for the overview
endpoint.

## Query parameters

- `page` integer: 1-indexed page.
- `per_page` integer: Rows per page (max 200).
- `search` string, nullable: Case-insensitive substring match on form name/id.
- `source_id` string, nullable: Filter to a single write key / site.
- `sort_field` 'submissions_30d' | 'total_submissions' | 'latest_submitted_at' | 'form_tag_id', nullable: total_submissions | latest_submitted_at | form_tag_id
- `sort_order` 'asc' | 'desc', nullable: asc | desc

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Response `200`

Successful Response

- ApiResponseFormsListResponse
  - `data` FormsListResponse, required: Paginated envelope for the forms list/search endpoint.
    - `items` FormSummary[]
      - `id` string, required: The form's HTML tag id (or the id-less group key).
      - `form_key` string, nullable: Alias for id; the addressable key for detail lookups.
      - `source_id` string, nullable: Write key / site the form was submitted from.
      - `display_name` string, nullable: Human-friendly name for the form.
      - `latest_submitted_at` string, date-time, nullable: Most recent submission timestamp.
      - `total_submissions` integer: Total submissions received for this form.
      - `page_url` string, nullable: URL of a page where the form was submitted.
      - `target_list_id` integer, nullable: Destination list id, if the form is routed.
      - `target_list_name` string, nullable: Destination list name, if the form is routed.
      - `delivery_source` string, nullable: Where this form's leads are delivered: 'route' (a tracked delivery route), 'legacy_mapping' (an older list mapping, delivered but not tracked per submission) or 'none' (nowhere). Same value the overview reports.
      - `delivery_health` string, nullable: 'failing' when at least one submission failed delivery; null otherwise.
      - `failed_submissions` integer, nullable: Submissions whose delivery failed or was only partly delivered (same count as the overview).
    - `page` integer
    - `per_page` integer
    - `total` integer
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)