# Filter reference One filter object is used in three places: `search_jobs` takes it as `filters`, `save_search` takes it as `prefilter`, and `check_prefilter` validates one and tells you how many postings it would catch. This page is that language. > **Gotcha** — A field name that is not in the catalogue is **refused**, not quietly ignored — > so a typo fails loudly rather than widening your filter. Read the conventions > below before writing your first one: three of them are not guessable, and all > three produce a refusal you cannot explain from the field alone. ## The five value shapes Each field has a type, and the type decides the envelope its value takes. Text is the odd one out and worth reading twice: **the operator IS the key**, and there is no `operator` field at all. **`text`** — the operator is the key; give one or more of them Operators: `all_words`, `any_words`, `exact_phrase`, `none_words` ```json { "": { "all_words": "python scraper", "none_words": "wordpress" } } ``` **`select`** — {"operator": , "values": \[, …]} Operators: `equals`, `equals_all`, `not_equals`, `not_equals_any` ```json { "": { "operator": "equals", "values": [ "" ] } } ``` **`numeric`** — {"operator": , "value1": ""} — "between" also needs value2 Operators: `between`, `equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals` ```json { "": { "operator": "greater_than", "value1": "1000" } } ``` **`boolean`** — {"value": "Yes"|"No"} — no operator key ```json { "": { "value": "Yes" } } ``` **`date`** — {"operator": , "date1": "YYYY-MM-DD"} — "between" also needs date2 Operators: `after`, `before`, `between`, `equals` ```json { "": { "operator": "after", "date1": "2026-01-01" } } ``` ## Conventions Three rules that no single field entry could tell you, and that produce refusals which make no sense until you know them. - **type names** — text,numeric,select,boolean,date - **numbers are strings** — numeric values go in as STRINGS — value1: "1000", not 1000. This is the v1 filter format the saved-search engine reads, and a real number is refused. - **booleans are yes no** — boolean values are the strings "Yes" and "No", not true and false, for the same reason. - **options are authoritative** — where a field carries `options`, that list is what the validator accepts. A field's prose `description` comes from the source system and may name values this corpus does not hold — engagement\_weeks and hourly\_budget\_type both do. Filter on `options`, never on the sentence. - **bounds are observed not enforced** — `min` and `max` are the range currently present in the corpus, not a constraint. A filter outside them is accepted and matches nothing; check\_prefilter warns when a clause cannot match. ## Combining filters Several fields in one object are ANDed. There is no OR across fields; to widen, loosen a clause rather than adding another. Within a text field, `any_words` is the OR. ```json { "_combined|title|description|skills": { "exact_phrase": "React Native" }, "buyer_payment_verified": { "value": "Yes" }, "total_spent": { "operator": "greater_than", "value1": "5000" } } ``` Run it through `check_prefilter` before saving. It returns `matched`, and a filter that catches nothing looks exactly like a quiet market — a saved search built on one fires forever without telling you it was the filter. It also returns `warnings` when a clause cannot match at all, such as a numeric comparison outside the range the corpus holds. ## Every field Bounds are values observed in the corpus, not limits — a filter outside them is valid and matches nothing. | field | type | label | what it means | values | | --------------------------- | ------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `avg_hourly_rate` | numeric | Client Avg Hourly Rate | Average hourly rate this client typically pays freelancers. Based on their historical hiring patterns. | | | `buyer_feedback_count` | numeric | Buyer Feedback Count | Number of feedbacks the client has received. | 0–22131 | | `buyer_payment_verified` | boolean | Buyer Payment Verified | Boolean flag indicating whether the client has verified their payment method on Upwork. | | | `buyer_score` | numeric | Buyer Score | Score of the client's performance on Upwork. | 0–5 | | `category_name` | select | Category Name | Main category of the job (e.g., Web Development, Data Science, Design). Upwork's primary job classification. | `Accounting & Consulting`, `Admin Support`, `Customer Service`, `Data Science & Analytics`, `Design & Creative`, `Engineering & Architecture`, … | | `experience_level` | select | Experience Level | Required experience level for the job. Exact values: Entry\_level, Intermediate, Expert. | `Entry_level`, `Expert`, `Intermediate` | | `hire_rate` | numeric | Client Hire Rate | Percentage of freelancers the client has hired from total applications. Higher rates indicate clients who actively hire rather than just browse. | | | `hires` | numeric | Hires | Total number of freelancers hired by the client. | 0–39261 | | `named_buyer` | boolean | Only named buyers | Keep only jobs whose client we've identified by name (resolved via BuyerLookup) — established, researchable clients, not anonymous/brand-new ones. | | | `price` | numeric | Budget/Price - Fixed-price | The budget amount for the fixed-price job. | 0–1000000 | | `price_max` | numeric | Hourly Rate - Max | Upper end of the job's hourly rate band (Upwork jobs advertise a range like $10-35/hr). Hourly jobs only - fixed-price jobs carry their budget in `price` and leave this empty. | 3–999 | | `price_min` | numeric | Hourly Rate - Min | Lower end of the job's hourly rate band (Upwork jobs advertise a range like $10-35/hr). Hourly jobs only - fixed-price jobs carry their budget in `price` and leave this empty. | 3–500 | | `search` | text | Keyword search | Search across title + description + skills together — the main 'what work' filter. | | | `skills` | text | Skills | Comma-separated list of required skills and technologies for the job as specified by the client. | | | `subcategory_name` | select | Subcategory Name | Specific subcategory within the main category (e.g., Front-End Development, Machine Learning). More granular classification. | `3D Modeling & CAD`, `AI & Machine Learning`, `AI Apps & Integration`, `Accounting & Bookkeeping`, `Art & Illustration`, `Audio & Music Production`, … | | `title` | text | Job Title | The job posting title as written by the client. Contains the main description of what work needs to be done. | | | `total_spent` | numeric | Total Spent | Total amount the client has spent on Upwork across all their projects. | 0.08–22117578.16 | | `active_hires` | numeric | Active Hires | Number of freelancers currently hired by the client. | 0–4835 | | `client_location` | select | Client Location | Geographic location of the client posting the job. | `United States`, `United Kingdom`, `India`, `USA`, `Australia`, `Canada`, … | | `contract_to_hire` | boolean | Contract To Hire | Whether the job has potential to convert from contract to permanent employment. | | | `description` | text | Description | Full job description text as written by the client. Contains detailed requirements, expectations, and project scope. | | | `engagement_label` | select | Engagement Label | Expected duration or type of engagement (e.g., 1 to 3 months, 3 to 6 months, Less than 1 month, Less than 1 week, More than 6 months). | `1 to 3 months`, `3 to 6 months`, `Less than 1 month`, `More than 6 months` | | `engagement_weeks` | select | Engagement Weeks | Project duration in weeks. Options: 1, 3, 9, 18, 52 weeks. | `3`, `9`, `18`, `52` | | `industry` | select | Industry | Main industry the client operates in. Select from available choices. | `Aerospace`, `Agriculture & Forestry`, `Art & Design`, `Automotive`, `Aviation`, `Education`, … | | `job_is_premium` | boolean | Job Is Premium | Boolean flag indicating whether job is premium applies to this job. | | | `jobs_posted` | numeric | Jobs Posted | Total number of jobs the client has posted on Upwork. | 0–39636 | | `open_jobs` | numeric | Open Jobs | Number of jobs the client currently has open/active. | 0–415 | | `price_type` | select | Price Type | How the job is priced: Fixed Price (one-time payment) or Hourly (paid per hour worked). | `Fixed-price`, `Hourly` | | `qual_portfolio_required` | boolean | Qual Portfolio Required | Whether the client requires a portfolio or work samples to apply. | | | `qual_pref_english` | select | Qual Pref English | Client's preferred English proficiency level for freelancers. | `ANY`, `CONVERSATIONAL`, `FLUENT`, `NATIVE` | | `qual_rising_talent` | boolean | Qual Rising Talent | Whether the job is open to Upwork Rising Talent (newer freelancers with potential). | | | `qual_type` | select | Qual Type | Type of freelancer the client is looking for: Agency (team/company), Independent (solo freelancer), or Any (no preference). | `AGENCY`, `ANY`, `INDEPENDENT` | | `total_hours` | numeric | Total Hours | Total number of hours the client has worked on Upwork across all their projects. | 0–11820879 | | `buyer_contract_date` | date | Buyer Contract Date | Date when the client first registered their account on Upwork. Indicates how long the client has been active on the platform. | | | `category_id` | select | Category ID | Numeric id of the job category — prefer Category Name. | `531770282580668416`, `531770282580668417`, `531770282580668418`, `531770282580668419`, `531770282580668420`, `531770282580668421`, … | | `client_invites_sent` | numeric | Client Invites Sent | Invites the client had sent when the job was captured, minutes after posting. Clients usually send invites while creating the job, so this catches invite-first postings. 0 when the source reported none (NULLs backfilled to 0 on 2026-08-22 — before that, numeric filters silently dropped the unreported rows). | 0–349 | | `client_positions_to_hire` | numeric | Client Positions To Hire | Number of client positions to hire. | 0–99 | | `client_total_applicants` | numeric | Applicants (this job) | How many freelancers have applied to this posting so far. | 0–67 | | `client_total_hired` | numeric | Hired (this job) | How many freelancers the client has already hired on this posting. | 0–41 | | `client_total_invited` | numeric | Invited (this job) | How many freelancers the client invited to this posting. | 0–52 | | `client_unanswered_invites` | numeric | Unanswered invites | Invites the client sent that went unanswered. | 0–302 | | `company_size` | select | Company Size | Size of the client's company. Predefined option for company size. Select from available choices. | `0`, `1`, `10`, `100`, `1000`, `10000`, … | | `hourly_budget_type` | select | Hourly Budget Type | Type of hourly budget. Options: AS\_NEEDED, DEFAULT, FULL\_TIME, MANUAL, NOT\_PROVIDED, NOT\_SURE, PART\_TIME. | `DEFAULT`, `MANUAL`, `NOT_PROVIDED` | | `qual_min_hours` | select | Qual Min Hours | Predefined option for qual min hours. Select from available choices. | `0` | | `qual_min_hours_week` | select | Qual Min Hours Week | Minimum hours per week required for hourly jobs. Options: 10, 30, 40. | `0`, `10`, `30`, `40` | | `qual_min_success_score` | select | Qual Min Success Score | Minimum Upwork success score required to apply for the job. | `0`, `80`, `90` | | `subcategory_id` | select | Subcategory ID | Numeric id of the job subcategory — prefer Subcategory Name. | `531770282584862724`, `531770282584862725`, `531770282584862726`, `531770282584862728`, `531770282584862730`, `531770282584862733`, … |