GET /v1/projects

List projects

Access

Authenticated

project:read

Cost

Free

Rate limit

60 / minute per account

Quota

None

Your account projects, newest activity first. Each row carries the derived counts, the company the role hires for (its display name resolved for an agency client and for in-house hiring alike), and any managed agents Vamo is running on it.

Query parameters

limit integer default: 25

min 1, max 100
offset integer | null default: 0

min 0, max 100000
status string

activepausedarchived

Responses

200 The projects
- rows array of Project required
  
  This page of projects.
  - id string required
    
    The project id.
  - name string required
    
    The project name, usually the role being hired for.
  - status string required
    
    Where the project stands.
  - companyRef ProjectCompanyRef required
    
    The company this role hires for. Null only on projects created before companies existed.
    
    subjectType string required
    
    What kind of company record this points at: a client company on this account, or the account’s own profile.
    
    subjectId string required
    
    The id of that record.
  - companyName string | null required
    
    That company’s display name, resolved for you. Null only when no printable name is on file.
  - createdBy string | null required
    
    The member or key that created the project. Null when unknown.
  - createdAt string required
    
    When the project was created, as an ISO 8601 instant.
  - updatedAt string required
    
    When it last changed, as an ISO 8601 instant.
  - candidateListId string | null required
    
    The shortlist holding this project’s candidates. Every project gets one at creation.
  - managedAgents array of ProjectManagedAgent required
    
    Vamo-managed agents working this project. Empty on an ordinary project; a project can have any number.
    
    id string required
    
    The managed agent id.
    
    name string required
    
    The agent’s name.
    
    status string required
    
    Where the agent stands on this project.
  - stats object required
    
    Candidate, sequence and outreach counters for this project.
    
    candidates integer required
    
    How many candidates are on this project.
    
    sequences integer required
    
    How many outreach sequences are running for it.
    
    contacted integer required
    
    Distinct people who have actually had at least one message sent to them on this project. Not the number of messages, and not the number scheduled.
    
    replyRate number | null required
    
    Replies as a fraction of people contacted, 0 to 1. Null when nobody has been contacted yet, which is different from a rate of zero.
- total integer required
  
  How many projects match the filters in total, not just on this page.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
403 Missing project:read
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.