Skip to main content
GET
List pitches

Authorizations

Authorization
string
header
required

Key from Profile. Send Authorization: Bearer yb_....

Query Parameters

x-vercel-protection-bypass
string

Optional. Vercel Protection Bypass for Automation — use when calling the Staging server.

limit
integer
default:20

Page size. 1–50. Default 20.

Required range: 1 <= x <= 50
cursor
string

Opaque cursor from the previous page's next_cursor. Must be used with the same sort.

Minimum string length: 1
sort
enum<string>
default:post_date

post_date is when Yellowbrick added the pitch. pitch_returns is the write-up's realized return. investor_returns is the author's return.

Available options:
post_date,
pitch_returns,
investor_returns
extraTags
string[]

Tag slugs this request must match. Get every slug from GET /api/v1/tags, including author badge, author return, win rate, pitch return, sentiment, position, and paywall. Repeat the parameter or comma-separate. Slugs are grouped by type: OR within a type, AND across types. Invert a type with extraTagsNoneOf. Quality filters also have typed parameters (authorBadge, authorReturn, winRateGte, pitchReturn) which compile to these slugs.

Minimum string length: 1
extraTagsNoneOf
string[]

Tag type keys to invert in extraTags, not slugs. Use tagTypeKey from GET /api/v1/tags sections (for example pitch_category, strategy, author_return, badge). Pitches that match that type's extraTags slugs are excluded.

Minimum string length: 1
authorBadge
enum<string>[]

Author badge: elite or rising. Repeat to include both (OR). Same filter as the badge slugs in GET /api/v1/tags.

Available options:
elite,
rising
authorReturn
enum<string>[]

Author return floor. {period}_{abs|excess}_gte_{0|10|25|50} where period is 6m, 1y, or 2y. abs is absolute return; excess is versus the market. Repeat to OR. Same values as GET /api/v1/tags author_return (without the col_author_return_ prefix).

Available options:
6m_abs_gte_0,
6m_abs_gte_10,
6m_abs_gte_25,
6m_abs_gte_50,
6m_excess_gte_0,
6m_excess_gte_10,
6m_excess_gte_25,
6m_excess_gte_50,
1y_abs_gte_0,
1y_abs_gte_10,
1y_abs_gte_25,
1y_abs_gte_50,
1y_excess_gte_0,
1y_excess_gte_10,
1y_excess_gte_25,
1y_excess_gte_50,
2y_abs_gte_0,
2y_abs_gte_10,
2y_abs_gte_25,
2y_abs_gte_50,
2y_excess_gte_0,
2y_excess_gte_10,
2y_excess_gte_25,
2y_excess_gte_50
winRateGte
enum<string>[]

Author 1-year win rate floor in percent: 50, 60, or 75. Requires at least 8 pitches. Repeat to OR.

Available options:
50,
60,
75
pitchReturn
enum<string>[]

Pitch return floor. {period}_{abs|excess}_gte_pct{0|25|50|100} or {period}_{abs|excess}_gte_x{2|3|4|10}. Repeat to OR. Same values as GET /api/v1/tags pitch_return (without the col_pitch_return_ prefix).

Available options:
6m_abs_gte_pct0,
6m_abs_gte_pct25,
6m_abs_gte_pct50,
6m_abs_gte_pct100,
6m_abs_gte_x2,
6m_abs_gte_x3,
6m_abs_gte_x4,
6m_abs_gte_x10,
6m_excess_gte_pct0,
6m_excess_gte_pct25,
6m_excess_gte_pct50,
6m_excess_gte_pct100,
6m_excess_gte_x2,
6m_excess_gte_x3,
6m_excess_gte_x4,
6m_excess_gte_x10,
1y_abs_gte_pct0,
1y_abs_gte_pct25,
1y_abs_gte_pct50,
1y_abs_gte_pct100,
1y_abs_gte_x2,
1y_abs_gte_x3,
1y_abs_gte_x4,
1y_abs_gte_x10,
1y_excess_gte_pct0,
1y_excess_gte_pct25,
1y_excess_gte_pct50,
1y_excess_gte_pct100,
1y_excess_gte_x2,
1y_excess_gte_x3,
1y_excess_gte_x4,
1y_excess_gte_x10,
2y_abs_gte_pct0,
2y_abs_gte_pct25,
2y_abs_gte_pct50,
2y_abs_gte_pct100,
2y_abs_gte_x2,
2y_abs_gte_x3,
2y_abs_gte_x4,
2y_abs_gte_x10,
2y_excess_gte_pct0,
2y_excess_gte_pct25,
2y_excess_gte_pct50,
2y_excess_gte_pct100,
2y_excess_gte_x2,
2y_excess_gte_x3,
2y_excess_gte_x4,
2y_excess_gte_x10
sentiment
enum<string>[]

Pitch sentiment: bullish, bearish, or neutral. Repeat to OR.

Available options:
bullish,
bearish,
neutral
positionDecision
enum<string>[]

Extracted position action, such as initiate_long or hold. Repeat to OR. Full list is GET /api/v1/tags position_decision.

Available options:
initiate_long,
initiate_short,
increase_long,
increase_short,
reduce_long,
reduce_short,
close_long,
close_short,
hold,
monitor,
pass_idea,
not_specified
isPremiumPitch
enum<string>

true for paywalled write-ups, false for free ones.

Available options:
true,
false
followingOnly
boolean
default:false

When true, only authors the key owner follows.

authorUsername
string

Author username without @. Get it from GET /api/v1/search (authors[].username). Limits the list to that author.

Minimum string length: 1
companyId
integer

Company id from GET /api/v1/search (companies[].companyId). Limits the list to pitches on that company.

Required range: x <= 9007199254740991
addedOnFrom
string

Inclusive start date (YYYY-MM-DD) for when Yellowbrick added the pitch. If you send only one bound, both ends use that day.

Pattern: ^\d{4}-\d{2}-\d{2}$
addedOnTo
string

Inclusive end date (YYYY-MM-DD) for when Yellowbrick added the pitch.

Pattern: ^\d{4}-\d{2}-\d{2}$
filterSetIds
string[]

Saved filter set ids for the key owner. List them with GET /api/v1/filter-sets. Repeat the parameter or comma-separate. A pitch matches if it matches any listed set (OR). Combined with extraTags and the other filters using AND. Maximum 100 ids.

Maximum array length: 100
Minimum string length: 1

Response

Pitch page

data
object[]
required
has_more
boolean
required

True when another page is available.

next_cursor
string

Pass as cursor to fetch the next page.

head_cursor
string

Cursor for the first item on this page.