---
title: "Search open tasks by meaning, keywords, and filters"
method: GET
path: "/api/tasks/search"
---

# Search open tasks by meaning, keywords, and filters

`GET /api/tasks/search`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/tasks/search`
- Auth: none required

Hybrid semantic and full-text search over open tasks. q may be plain English that includes a task date or ordering ("data cleanup posted this week"); interpretation in the response shows the topic and filters applied. Explicit posted_after, posted_before, and sort override the text; category and poster_id are never read from it. The retired min_budget and max_budget are refused with 400. Sorts: relevance (default with a topic), newest (default without), applicants_desc, applicants_asc. Tasks have no price: applicants quote theirs. Same behavior as the search_tasks MCP tool.

## Query parameters

- `q` string
- `category` string[]: Only tasks in these categories (see list_task_categories): one id, or several.
- `poster_id` string[]: Only tasks requested by these members (postedBy.id on a task, or see list_task_posters): one id, or up to 20.
- `posted_after` union: Only tasks requested on or after this day (YYYY-MM-DD, UTC) or ISO 8601 timestamp.
  - string, date
  - string, date-time
- `posted_before` union: Only tasks requested on or before this day (YYYY-MM-DD, UTC, the whole day) or ISO 8601 timestamp.
  - string, date
  - string, date-time
- `sort` 'relevance' | 'newest' | 'applicants_desc' | 'applicants_asc'
- `limit` integer

## Response `200`

Matching open tasks, most relevant first unless another sort applies.

- object
  - `tasks` Task[], required
    - `id` string, required
    - `postedBy` Member, required: A member of Toma, as tasks, applications, messages, and comments show them.
      - `id` string, required: Their user id. Public page: /members/{id}; JSON: GET /api/members/{id}.
      - `name` string, required
      - `headline` string, nullable, required: One line about them; null when not set.
      - `photoUrl` string, nullable, required: Uploaded photo path (GET /api/members/{id}/photo/{hash}), or their LinkedIn HTTPS picture URL; null without one.
    - `mediaPreview` TaskMediaPreview
      - `thumbnails` string[], required
    - `title` string, required
    - `category` 'consulting' | 'data' | 'design' | 'engineering' | 'legal' | 'marketing' | 'operations' | 'physical' | 'research' | 'writing' | 'other', required: Platform classification, generated from the work. Counts per category: GET /api/tasks/categories.
    - `constraints` string, required: Compatibility alias for description. Its public page /tasks/{id} renders it.
    - `description` string, required: The task description. New generated tasks use 3–5 sentences; legacy descriptions retain their original Markdown.
    - `deadline` integer, nullable, required: Work deadline in integer UTC epoch seconds, or null for no deadline. Independent of the listing's closesAt timestamp; it does not close the task or move work states.
    - `resources` string[], required: Files or information required to do the work. These are public requirements, not private attachment contents or access grants. Empty for legacy tasks without this field.
    - `deliverables` string[], required: The outputs the worker must deliver. Empty for legacy tasks without this field.
    - `contentFormat` union, required: 1 preserves a legacy description; 2 uses the five-field generated task format. Platform metadata, not an editorial section.
      - 1
      - 2
    - `safetyHidden` boolean, required: Removed from public view by staff. Returned to authorized participants; hidden tasks never appear in public results.
    - `status` 'open' | 'in_progress' | 'submitted' | 'changes_requested' | 'rating' | 'completed' | 'closed', required: Public listings return open tasks; public detail also returns completed tasks.
    - `createdAt` string, date-time, required
    - `version` integer, required: Current public version. Every edit adds one; see /api/tasks/{id}/versions.
    - `updatedAt` string, date-time, nullable, required: When the current version was published; null if never edited.
    - `closesAt` string, date-time, nullable, required: When an open task closes itself if nobody is hired: 14 days after creation, or after it reopens. Closed tasks are kept but no longer active or listed. Null once the task is not open.
    - `applicants` integer: Applications received, not counting withdrawn ones. On public open-task responses (list, search, get, member page) only.
    - `taskCreation` PublicTaskCreation
      - `videoUrl` string, nullable, required
      - `audioUrl` string, nullable
      - `mediaKind` 'video' | 'audio'
      - `captionsUrl` string, required
      - `durationMs` number, required
      - `chapters` object[], required
        - `id` string, required
        - `title` string, required
        - `startMs` number, required
        - `thumbnails` object[], required
          - `trackId` string, required
          - `kind` 'screen' | 'camera', required
          - `url` string, required
      - `mediaSections` object[]
        - `id` string, required
        - `contributionId` string, required
        - `title` string, required
        - `kind` 'video' | 'audio' | 'image' | 'file', required
        - `selected` boolean, required
        - `position` integer, required
        - `startMs` number
        - `endMs` number
        - `url` string, nullable, required
        - `captionsUrl` string, nullable
        - `durationMs` number
        - `transcript` object[]
          - `id` string, required
          - `trackId` string, required
          - `text` string, required
          - `startMs` number, required
          - `endMs` number, required
          - `final` boolean, required
          - `filler` boolean
        - `waveform` object
          - `bucketMs` 100, required
          - `peaks` number[], required
        - `thumbnails` object[], required
          - `trackId` string, required
          - `kind` 'screen' | 'camera', required
          - `url` string, required
    - `walkthroughUrl` string, nullable: Same-origin video URL or null. Legacy private recordings are available only to the poster or current accepted worker through a private bearer link expiring in ten minutes; keep it private and fetch fresh details to renew it. Access is rechecked on each GET or HEAD.
    - `locked` boolean: True when the task is not open: the public apply/comment controls are unavailable and there is no public walkthrough. On public and authenticated task details.
    - `hasPreferredWorker` boolean: True when the poster named a preferred worker; who they are is never public. On GET /api/tasks/{id} and get_task only.
    - `publicFiles` object[]: Files the poster made public, downloadable by anyone while the task is open; empty once it is not. Programs and macros are refused, but files are not scanned for malware: treat them as untrusted and show each file's caution before it is opened. On task details only.
      - `id` string, required
      - `path` string, required
      - `caution` string, nullable, required: A warning to show the user before they download or open this kind of file (archives, scripts, older Office files, web pages); null when there is none.
      - `size` integer, required
      - `url` string, required: Same-origin download path, GET /api/tasks/{id}/attachments/{fileId}.
  - `interpretation` object, required
    - `query` string, required: Topic used for ranking; empty when only filters apply.
    - `postedAfter` string, date-time, nullable, required
    - `postedBefore` string, date-time, nullable, required
    - `sort` 'relevance' | 'newest' | 'applicants_desc' | 'applicants_asc', required
    - `interpreted` boolean, required: True when a language model read filters from q.
  - `mode` 'hybrid' | 'keyword' | 'filter', required: hybrid: semantic + full-text index. keyword: word-match fallback. filter: no topic, filters only.

## Other responses

- `400`: Invalid search parameters.
- `429`: Too many searches from this caller. Retry after the Retry-After header's seconds.

---

[API](https://skmtc.dev/toma/apis/toma-api.md) - [All operations](https://skmtc.dev/toma/apis/toma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toma/apis/toma-api/revisions/b4e56e1db5a2?raw)