Search rows

POST

/v1/boards/{id}/search

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{ \"query\": \"hero video\", \"filters\": [ { \"column_id\": \"c6873aab-85de-4200-9afc-43470b21cf4c\", \"operator\": \"equals\", \"value\": \"Meta\" } ], \"sort\": \"position\", \"order\": \"asc\", \"limit\": 25, \"cursor\": \"eyJvIjoyNX0\", \"fields\": [ \"id\" ], \"columns\": [ \"Status\", \"Channel\" ] }");

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search"),
    Headers =
    {
        { "Authorization", "Bearer <token>" },
    },
    Content = new StringContent("{ \"query\": \"hero video\", \"filters\": [ { \"column_id\": \"c6873aab-85de-4200-9afc-43470b21cf4c\", \"operator\": \"equals\", \"value\": \"Meta\" } ], \"sort\": \"position\", \"order\": \"asc\", \"limit\": 25, \"cursor\": \"eyJvIjoyNX0\", \"fields\": [ \"id\" ], \"columns\": [ \"Status\", \"Channel\" ] }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search"

  payload := strings.NewReader("{ \"query\": \"hero video\", \"filters\": [ { \"column_id\": \"c6873aab-85de-4200-9afc-43470b21cf4c\", \"operator\": \"equals\", \"value\": \"Meta\" } ], \"sort\": \"position\", \"order\": \"asc\", \"limit\": 25, \"cursor\": \"eyJvIjoyNX0\", \"fields\": [ \"id\" ], \"columns\": [ \"Status\", \"Channel\" ] }")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"query\": \"hero video\", \"filters\": [ { \"column_id\": \"c6873aab-85de-4200-9afc-43470b21cf4c\", \"operator\": \"equals\", \"value\": \"Meta\" } ], \"sort\": \"position\", \"order\": \"asc\", \"limit\": 25, \"cursor\": \"eyJvIjoyNX0\", \"fields\": [ \"id\" ], \"columns\": [ \"Status\", \"Channel\" ] }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"query\": \"hero video\", \"filters\": [ { \"column_id\": \"c6873aab-85de-4200-9afc-43470b21cf4c\", \"operator\": \"equals\", \"value\": \"Meta\" } ], \"sort\": \"position\", \"order\": \"asc\", \"limit\": 25, \"cursor\": \"eyJvIjoyNX0\", \"fields\": [ \"id\" ], \"columns\": [ \"Status\", \"Channel\" ] }");
Request request = new Request.Builder()
  .url("https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  data: {
    query: 'hero video',
    filters: [
      {
        column_id: 'c6873aab-85de-4200-9afc-43470b21cf4c',
        operator: 'equals',
        value: 'Meta'
      }
    ],
    sort: 'position',
    order: 'asc',
    limit: 25,
    cursor: 'eyJvIjoyNX0',
    fields: ['id'],
    columns: ['Status', 'Channel']
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"query":"hero video","filters":[{"column_id":"c6873aab-85de-4200-9afc-43470b21cf4c","operator":"equals","value":"Meta"}],"sort":"position","order":"asc","limit":25,"cursor":"eyJvIjoyNX0","fields":["id"],"columns":["Status","Channel"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{ \"query\": \"hero video\", \"filters\": [ { \"column_id\": \"c6873aab-85de-4200-9afc-43470b21cf4c\", \"operator\": \"equals\", \"value\": \"Meta\" } ], \"sort\": \"position\", \"order\": \"asc\", \"limit\": 25, \"cursor\": \"eyJvIjoyNX0\", \"fields\": [ \"id\" ], \"columns\": [ \"Status\", \"Channel\" ] }")
val request = Request.Builder()
  .url("https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

use serde_json::json;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search";

    let payload = json!({
        "query": "hero video",
        "filters": (
            json!({
                "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c",
                "operator": "equals",
                "value": "Meta"
            })
        ),
        "sort": "position",
        "order": "asc",
        "limit": 25,
        "cursor": "eyJvIjoyNX0",
        "fields": ("id"),
        "columns": ("Status", "Channel")
    });

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.post(url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request POST \
  --url https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "hero video", "filters": [ { "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c", "operator": "equals", "value": "Meta" } ], "sort": "position", "order": "asc", "limit": 25, "cursor": "eyJvIjoyNX0", "fields": [ "id" ], "columns": [ "Status", "Channel" ] }'

wget --quiet \
  --method POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --body-data '{ "query": "hero video", "filters": [ { "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c", "operator": "equals", "value": "Meta" } ], "sort": "position", "order": "asc", "limit": 25, "cursor": "eyJvIjoyNX0", "fields": [ "id" ], "columns": [ "Status", "Channel" ] }' \
  --output-document \
  - https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/search

Find rows on a board by text and/or column conditions — the question-answering counterpart to GET /v1/boards/{id}/rows, which enumerates.

query is a case-insensitive substring match over the row’s title and its human-readable cell text: text, link and richtext values, plus the option and user names behind tags and user cells — so query: "sarah" finds the rows assigned to her without you resolving her id first. filters express the precise conditions — one entry per column, each with an operator (equals, not_equals, contains, gt/gte/lt/lte, is_empty, is_not_empty) — and combine with AND, alongside query. Discover column ids and types with GET /v1/boards/{id}/columns.

A filter naming an unknown column, an option the column doesn’t have, or a comparison its type can’t honour is a 400 listing every problem at once — filters are never silently dropped, since that would return a wider result set than you asked for.

Response items are the same Row shape as the list feeds, plus total: the exact number of matching rows across all pages. Results are ordered by sort (position — the board’s own order — by default), so paging rides an opaque offset next_cursor rather than the (created_at, id) keyset the list endpoints use; treat it as opaque and pass it straight back. Archived rows are excluded.

POST is used for the request-body filters; the call reads state and creates nothing — no Idempotency-Key applies.

Pass fields to trim each row to the properties you actually need — e.g. "fields": ["title", "html_url"] returns just those (plus id, always). Unknown names are rejected rather than ignored. Pass columns (ids or names) to narrow each row’s fields array. Neither narrows what gets searched — you can filter on a column you’ve projected out of the response.

The search covers the whole board, up to 50,000 rows. On a larger board the response sets truncated: true and only the most recently updated 50,000 rows are searched; a truncated empty result means “not found among the rows searched”, not “not on the board”.

Returns 404 when the board doesn’t exist, belongs to another organization, or sits outside the token’s space allow-list.

Required scope: boards:read. Rate-limit cost: 10.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

24ce3d43-516c-4375-9d51-e9a2c8333683

Request Body^required

application/json

object

query

Free-text query — a case-insensitive substring match (≤200 chars) over the row’s title and its human-readable cell text: text, link and richtext values, plus the option / user names behind tags and user cells (and mediacolumn cells mirroring either). Ids, numbers, checkboxes and dates aren’t matched by text — use filters for those.

string

<= 200 characters

Example

hero video

filters

Per-column conditions. A row must satisfy every entry (AND); within an entry a value array is any-of. A filter naming an unknown column, or one its column’s type can’t honour, is a 400 — never silently dropped, which would widen the result set.

Array<object>

object

column_id

required

The column to filter on — a Column.id from GET /v1/boards/{id}/columns.

string format: uuid

Example

c6873aab-85de-4200-9afc-43470b21cf4c

operator

required

How the cell is compared to value:

equals / not_equals — the cell holds (or doesn’t hold) the value. A multi-value cell matches on any of its values, so not_equals reads as “has none of these”. Strings are case-insensitive; date compares by calendar day.
contains — case-insensitive substring of the cell’s text. Not on id-backed cells (tags, user, media, relation) — use equals (it accepts option names) or query.
gt / gte / lt / lte — against a single number or ISO date.
is_empty / is_not_empty — whether the cell holds anything. Takes no value, and the only operators available on structured cells (checklist, insights, metricsdata, externaldata, mediaattribute).

string

Allowed values: equals not_equals contains gt gte lt lte is_empty is_not_empty

value

Any of:

Array
object

Array

Any of:

string

sort

Result ordering. position (default) is the board’s own row order, so results read like the board itself; rows with no position sort last in either direction.

string

Allowed values: position title created_at updated_at

order

Sort direction. Defaults to asc for position and title, desc for created_at and updated_at.

string

Allowed values: asc desc

limit

Max rows per page (1–100). Default 25.

integer

>= 1 <= 100

Example

cursor

Pagination cursor returned as next_cursor from the previous page.

string

Example

eyJvIjoyNX0

fields

Return only these properties of each row, instead of the full object. id is always included. Omit for the complete object.

Array<string>

Allowed values: id board_id parent_id title position fields organization_id space_id archived created_at updated_at html_url

columns

Return only these columns in each row’s fields, instead of every column on the board. Accepts column ids or names (case-insensitive); an entry matching no column is rejected. fields come back in the order listed here; omit for every column, in the board’s own column order. Passing this keeps each row’s fields array even when the fields parameter omits it — selecting columns is asking for cells.

Array<string>

Example

[
  "Status",
  "Channel"
]

Responses

200

application/json

object

data

required

Array<object>

object

required

string format: uuid

board_id

required

string format: uuid

parent_id

required

Parent row id when this row is nested under another row; null for top-level rows.

string format: uuid

nullable

title

required

Convenience hoist of the title column’s value (the row’s display name). The same value also appears as a fields entry.

string

nullable

position

required

Row’s sort position within its board, lower values render first. Hoisted from the internal order field so clients can sort without an extra /columns call. May be fractional.

number

nullable

fields

required

Self-describing column values for this row — one entry per column, in the column’s display order. A multi-value column carries an array value; a single-value column a scalar. A column with no stored value is still listed, with an empty value ([] / null); archived columns and orphan storage keys are omitted.

Array<object>

object

column_id

required

Stable UUID of the column this value belongs to. Match against Column.id from GET /v1/boards/{id}/columns.

string format: uuid

column_name

required

Human-readable column label, mirrors what users see in the UI.

string

type

required

The kind of column this value belongs to. Combined with multiple, tells you the JSON type of value (for a multi-value column it’s the type of each array element):

number / rating → JSON number
checkbox → JSON true / false
date / updatedat → ISO 8601 string
tags / user / media / relation / list → JSON string
richtext → Markdown string
mediacolumn → the referenced media attribute’s type (e.g. a user attribute stores user id strings)
checklist / insights / metricsdata / externaldata / mediaattribute → JSON object
everything else → JSON string

string

Allowed values: text media number tags checkbox user date color link rating richtext updatedat createdat relation mediacolumn externaldata creativeid checklist list insights mediaattribute metricsdata

multiple

required

Whether this column holds multiple values. When true, value is an array (one element per stored value); when false, value is a single scalar. For mediacolumn columns this reflects the referenced media attribute’s own setting.

boolean

value

required

Any of:

Array
object

Array

Any of:

string

display_value

required

Any of:

string
Array<string>

string

organization_id

required

string format: uuid

space_id

required

string format: uuid

archived

required

true when the row has been archived. List endpoints exclude archived rows by default, so this is always false for rows returned by GET /v1/boards/{id}/rows. Kept on the schema so clients know the field exists.

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

Browser URL that opens this row as a detail panel over its board in the Focal web app. Hand this to users as a clickable link to the exact row.

string

next_cursor

required

Pass back as cursor to fetch the next page. null on the last page.

string

nullable

has_more

required

true when another page is available. Equivalent to next_cursor !== null.

boolean

total

required

Number of rows on the board matching the search, across all pages — counted from the matches themselves, not estimated. When truncated is true this counts matches within the 50,000 rows searched only, not across the whole board.

integer

truncated

required

true when the board has more rows than one search reads (50,000) and only its most recently updated 50,000 rows were searched. Matching rows beyond that are not represented in data or total, so treat a truncated empty result as “not found among the rows searched”, not “not on the board”.

boolean

Example

{
  "data": [
    {
      "id": "6eee0a1d-ef35-45ee-b1c9-b95f1f54d652",
      "board_id": "24ce3d43-516c-4375-9d51-e9a2c8333683",
      "parent_id": "5d1a7c34-9b2e-4f60-8a15-2c7e90b1d4f8",
      "title": "Hero video – 4:5 cut",
      "position": 2,
      "fields": [
        {
          "column_id": "3298a55a-c00c-4438-9a92-661ae534c8a3",
          "column_name": "Status",
          "type": "text",
          "multiple": false,
          "value": "In review",
          "display_value": "In review"
        },
        {
          "column_id": "c6873aab-85de-4200-9afc-43470b21cf4c",
          "column_name": "Channel",
          "type": "tags",
          "multiple": true,
          "value": [
            "9dc9bc29-97d0-48d0-afec-fdbc728d246d",
            "b2e7f6a1-3c48-4d95-a0e1-7f5c9d2b8a64"
          ],
          "display_value": [
            "Meta",
            "TikTok"
          ]
        },
        {
          "column_id": "993784a7-2dfc-4c80-b52b-0601abf0b58f",
          "column_name": "Launch date",
          "type": "date",
          "multiple": false,
          "value": "2027-03-15",
          "display_value": "2027-03-15"
        }
      ],
      "organization_id": "b46d9033-24b2-4441-87ad-2151088fde01",
      "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
      "archived": false,
      "created_at": "2027-03-04T10:15:00Z",
      "updated_at": "2027-03-06T14:42:00Z",
      "html_url": "https://app.focal.inc/spaces/6916bc3d-e1ab-425b-ac25-eefada01a9a2/boards/24ce3d43-516c-4375-9d51-e9a2c8333683?panel=row_6eee0a1d-ef35-45ee-b1c9-b95f1f54d652"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNy0wMy0wNFQxMDoxNTowMC4wMDBaIiwiaSI6Ijc4NmJlZWRhLTU1YWMtNDAyNS1iZjZlLTQzYjI5MThlODRhOSJ9",
  "has_more": true,
  "total": 12,
  "truncated": false
}

400

The request was malformed (invalid cursor, unknown type, validation failure, etc.). error.code is bad_request.

application/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body",
    "details": [
      {
        "field": "space_id",
        "issue": "Invalid UUID"
      }
    ]
  }
}

401

Missing, invalid, or disabled token. error.code is unauthenticated.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "unauthenticated",
    "message": "Bearer token is missing or invalid"
  }
}

403

The token doesn’t have the scope this endpoint requires. error.code is forbidden.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "forbidden",
    "message": "Token doesn't have the required scope"
  }
}

404

Resource doesn’t exist or is outside the token’s space allow-list. The two cases share a response shape so a restricted token can’t probe for the existence of out-of-scope spaces. error.code is not_found.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

429

Rate limit exceeded. error.code is rate_limited. Wait the number of seconds in the Retry-After header before retrying. Quotas are per-token; see the “Rate limiting” section at the top of this document.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 1000 units per 60s exceeded (this request cost 5)"
  }
}

Headers

Retry-After

integer

Example

Seconds to wait before retrying.

Search rows

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Example

Example

Example

Example

Example

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

429

Example

Headers

Example

Request Body^required