> ## Documentation Index
> Fetch the complete documentation index at: https://www.vollna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List proposals

> Returns the proposals of one Upwork profile. Without the search parameters this is the plain list: page and limit, sorted by submittedAt. Any of dateRange, templateId, variant, autoBiddingSetupId, groupId or cursor switches to the dashboard search: one profile or one profile group, pages through nextCursor, archived proposals and hidden members left out



## OpenAPI

````yaml get /proposals
openapi: 3.0.4
info:
  title: Vollna API
  description: API for managing Upwork profiles, proposals, results, and filters
  version: 1.0.0
servers:
  - url: https://api.vollna.com/v1
security: []
tags:
  - name: Profiles
    description: Manage Upwork profiles
  - name: Proposals
    description: Access and manage Upwork proposals
  - name: Results
    description: View monitoring results and projects
  - name: Filters
    description: Manage monitoring filters
  - name: Auto Bidding
    description: Manage auto bidding jobs and setups
  - name: Account
    description: The token team's account, plan and meters
  - name: Invitations
    description: Upwork invitations
  - name: Projects
    description: Upwork jobs and their competition
  - name: AI Qualifier
    description: A filter's AI qualifier and its verdicts
  - name: Market Insights
    description: Upwork market analytics and saved searches
  - name: Proposal Templates
    description: Proposal templates and their results
paths:
  /proposals:
    get:
      tags:
        - Proposals
      summary: List proposals
      description: >-
        Returns the proposals of one Upwork profile. Without the search
        parameters this is the plain list: page and limit, sorted by
        submittedAt. Any of dateRange, templateId, variant, autoBiddingSetupId,
        groupId or cursor switches to the dashboard search: one profile or one
        profile group, pages through nextCursor, archived proposals and hidden
        members left out
      parameters:
        - name: profileId
          in: query
          description: >-
            Upwork profile ID (from `/profiles` API endpoint). Required unless
            groupId is sent
          required: false
          schema:
            type: integer
        - name: organizationId
          in: query
          description: Organization ID (from `/organizations` API endpoint)
          deprecated: true
          schema:
            type: integer
        - name: page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page. 10 to 100 in the list, 1 to 50 in the search
          required: false
          schema:
            type: integer
            maximum: 100
            default: 20
        - name: sort
          in: query
          description: Sort field
          required: false
          schema:
            type: string
            enum:
              - submittedAt
            default: submittedAt
        - name: order
          in: query
          description: Sort order
          required: false
          schema:
            type: string
            enum:
              - ASC
              - DESC
            default: DESC
        - name: groupId
          in: query
          required: false
          description: >-
            Search: a profile group. Send it without organizationId and
            profileId
          schema:
            type: integer
            minimum: 1
        - name: dateRange
          in: query
          required: false
          description: >-
            A preset: today, yesterday, last_7_days, last_week, last_4_weeks,
            last_30_days, last_month, last_3_months, last_90_days,
            last_12_months, month_to_date, quarter_to_date, year_to_date or
            all_time. Or a custom range as YYYY-MM-DD_YYYY-MM-DD. Read in the
            team owner's time zone
          schema:
            type: string
            default: last_30_days
        - name: status
          in: query
          required: false
          description: >-
            Search only: one outcome. It does not switch to the search on its
            own
          schema:
            type: string
            enum:
              - sent
              - viewed
              - replied
              - hired
              - invitation
        - name: templateId
          in: query
          required: false
          description: 'Search: proposals sent with this proposal template'
          schema:
            type: integer
            minimum: 1
        - name: variant
          in: query
          required: false
          description: 'Search: one A/B variant'
          schema:
            type: string
            enum:
              - A
              - B
        - name: autoBiddingSetupId
          in: query
          required: false
          description: 'Search: proposals sent by this auto-bidding setup'
          schema:
            type: integer
            minimum: 1
        - name: cursor
          in: query
          required: false
          description: 'Search: nextCursor of the previous page'
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Proposal'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                    title: List
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            submittedAt:
                              type: string
                              format: date-time
                              nullable: true
                            job:
                              type: object
                              properties:
                                title:
                                  type: string
                                  nullable: true
                                url:
                                  type: string
                                  nullable: true
                            status:
                              type: string
                              enum:
                                - sent
                                - viewed
                                - replied
                                - hired
                                - invitation
                            viewed:
                              type: boolean
                            replied:
                              type: boolean
                            hired:
                              type: boolean
                            invitation:
                              type: boolean
                            connects:
                              type: integer
                              nullable: true
                            connectsReturned:
                              type: integer
                              nullable: true
                            boost:
                              type: integer
                              nullable: true
                            template:
                              type: object
                              nullable: true
                              properties:
                                id:
                                  type: integer
                                variant:
                                  type: string
                                  enum:
                                    - A
                                    - B
                            letterExcerpt:
                              type: string
                              nullable: true
                              description: Cut at 600 characters
                      nextCursor:
                        type: string
                        nullable: true
                        description: Pass as cursor for the next page
                    title: Search
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - apiToken: []
components:
  schemas:
    Proposal:
      type: object
      properties:
        applicationUid:
          type: string
          description: Application UID
          example: '1234567890123456789'
        submittedAt:
          type: string
          format: date-time
          description: Submission date and time
        coverLetter:
          type: string
          description: Cover letter
        answers:
          type: array
          items:
            type: object
            properties:
              question:
                type: string
                description: Client's question
              answer:
                type: string
                description: Your answer
        jobDetails:
          type: object
          description: >-
            Basic job info. Keys with no value are omitted, so the object can be
            empty.
          properties:
            title:
              type: string
              description: Job title
            postedAt:
              type: string
              format: date-time
              description: Job posted date and time
            url:
              type: string
              format: uri
              description: Link to the job posting on Upwork
        freelancer:
          type: object
          properties:
            id:
              type: integer
              description: Member ID
              example: 1
            fullName:
              type: string
              description: Member full name
              example: John Doe
            imagePath:
              type: string
              nullable: true
              description: Path to the member's avatar image
        businessManager:
          type: object
          properties:
            id:
              type: integer
              description: Member ID
              example: 2
            fullName:
              type: string
              description: Member full name
              example: Jane Doe
        upworkProfile:
          type: object
          description: Upwork profile details
          properties:
            id:
              type: integer
              description: Upwork profile ID
              example: 1
            label:
              type: string
              description: Upwork profile name
              example: ACME, Inc.
            type:
              type: string
              enum:
                - freelancer
                - agency
              description: Upwork profile type
              example: agency
        upworkOrganization:
          type: object
          deprecated: true
          description: Deprecated, use `upworkProfile` instead
          properties:
            id:
              type: integer
              description: Organization ID
              example: 1
            label:
              type: string
              description: Organization label
              example: ACME, Inc.
            type:
              type: string
              enum:
                - freelancer
                - agency
              description: Organization type
              example: agency
        connects:
          type: integer
          description: Connects spent
          example: 16
        boost:
          type: integer
          description: Boost
          example: 8
        terms:
          type: object
          properties:
            fixedPrice:
              type: number
              format: float
              description: Fixed price
              example: 1000
            hourlyRate:
              type: number
              format: float
              description: Hourly rate
              example: 100
            increasePercent:
              type: integer
              description: Increase percent
              example: 10
            increaseFrequency:
              type: integer
              description: Increase frequency in months
              example: 3
        isViewed:
          type: boolean
        isInterviewed:
          type: boolean
        isHired:
          type: boolean
        isWithdrawn:
          type: boolean
        isInvitation:
          type: boolean
        isArchived:
          type: boolean
        occupationUid:
          type: string
        occupationTitle:
          type: string
        submissionPosition:
          type: integer
          description: Submission position
          example: 3
        boostOutbid:
          type: boolean
        coverLetterVariant:
          type: integer
          nullable: true
          description: A/B cover letter variant number
        responseTimeMinutes:
          type: integer
          nullable: true
          description: >-
            Minutes between the job being posted and the proposal being
            submitted. Null when either time is unknown.
        attachments:
          type: array
          description: Files attached to the proposal. Empty array when none were captured.
          items:
            type: object
            properties:
              name:
                type: string
                description: File name
              sizeLabel:
                type: string
                description: Human-readable file size
                example: 1.2 MB
              url:
                type: string
                format: uri
                nullable: true
                description: Upwork download link
        biddingTemplate:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
        project:
          $ref: '#/components/schemas/Project'
          nullable: true
          description: Linked project from Vollna database (if found via Elasticsearch)
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
          example: 100
        page:
          type: integer
          description: Current page number
          example: 1
        limit:
          type: integer
          description: Number of items per page
          example: 20
        pages:
          type: integer
          description: Total number of pages
          example: 5
    Error:
      type: object
      properties:
        error:
          type: string
    Project:
      type: object
      description: >-
        A job posting. Fields derived from the posting are null when the
        marketplace does not provide them.
      properties:
        title:
          type: string
          description: Project title
        description:
          type: string
          nullable: true
          description: Project description
        skills:
          type: array
          items:
            type: string
          description: Required skills. Empty array when the posting lists none.
        url:
          type: string
          format: uri
          nullable: true
          description: Project URL on the marketplace
        publishedAt:
          type: string
          format: date-time
          nullable: true
          description: When the project was published
        publishedTimestamp:
          type: integer
          nullable: true
          description: >-
            Publish time as a Unix timestamp (seconds). Used as the cursor by
            the filter projects endpoint.
        usOnly:
          type: boolean
          description: Job restricted to US freelancers
        ukOnly:
          type: boolean
          description: Job restricted to UK freelancers
        durationLabel:
          type: string
          nullable: true
          description: Project length label
          example: 1 to 3 months
        engagementLabel:
          type: string
          nullable: true
          description: Weekly workload label
          example: Less than 30 hrs/week
        experienceLevel:
          type: string
          nullable: true
          description: Required experience level
          example: Intermediate
        jobType:
          type: string
          nullable: true
          description: Job type label
          example: Hourly
        jobAttachmentsCount:
          type: integer
          description: Number of files attached to the job posting
        connectsPrice:
          type: integer
          nullable: true
          description: Connects required to apply (Upwork)
        isFeatured:
          type: boolean
          nullable: true
          description: Whether the job is a featured (boosted) posting
        isUpworkEnterpriseClient:
          type: boolean
          nullable: true
          description: Whether the client is an Upwork Enterprise client
        preferredQualifications:
          type: object
          nullable: true
          description: >-
            Client's preferred qualifications. Each key is present only when the
            posting sets it.
          properties:
            minJobSuccessScore:
              type: number
              description: Minimum Job Success Score
              example: 90
            talentType:
              type: string
              enum:
                - Independent
                - Agency
              description: Preferred freelancer type
            risingTalent:
              type: string
              description: '"Yes" when the client prefers Rising Talent freelancers'
            prefEnglishSkill:
              type: string
              description: Preferred English level
            locations:
              type: array
              items:
                type: string
              description: Preferred freelancer locations
            languages:
              type: array
              items:
                type: string
              description: Preferred languages
        clientQuestions:
          type: array
          items:
            type: string
          nullable: true
          description: Screening questions from the client
        categories:
          type: array
          items:
            type: string
          description: Project categories
        site:
          type: string
          description: Source site (e.g. Upwork.com)
        budget:
          type: object
          nullable: true
          description: >-
            Human-readable budget. Null when the posting has no budget; see
            budgetRaw for numbers.
          properties:
            type:
              type: string
              enum:
                - Fixed price
                - Hourly rate
              description: Budget type
            amount:
              type: string
              nullable: true
              description: Formatted amount or range with currency symbol
              example: $15 - $25
        budgetRaw:
          type: object
          description: Budget as numbers
          properties:
            type:
              type: string
              enum:
                - hourly
                - fixed
                - 'no'
              description: Budget type. "no" means the posting doesn't specify a budget.
            fixedAmount:
              type: number
              nullable: true
              description: Fixed price
            hourlyMin:
              type: number
              nullable: true
              description: Hourly rate range, lower bound
            hourlyMax:
              type: number
              nullable: true
              description: Hourly rate range, upper bound
        clientHireRate:
          type: number
          format: float
          nullable: true
          description: >-
            Client's hire rate as a fraction between 0 and 1. Same value as
            clientDetails.hireRate.
          example: 0.72
        clientDetails:
          type: object
          description: >-
            Client stats. Each key is omitted when the value is empty or zero —
            check presence before reading.
          properties:
            paymentMethodVerified:
              type: boolean
              description: >-
                Whether client's payment method is verified. Omitted when not
                verified.
            country:
              type: string
              description: Client's country name
            totalSpent:
              type: string
              description: >-
                Total amount spent by client, formatted with a thousands suffix.
                A string, not a number.
              example: 103.5k
            totalHires:
              type: integer
              description: Total number of hires by client
              example: 24
            hireRate:
              type: number
              format: float
              description: Client's hire rate as a fraction between 0 and 1
              example: 0.72
            avgHourlyRatePaid:
              type: number
              format: float
              description: Average hourly rate the client has paid
              example: 32.5
            rating:
              type: number
              format: float
              description: Client's rating
              example: 4.9
            reviews:
              type: integer
              description: Number of client reviews
              example: 18
            city:
              type: string
              description: Client's city
            countryTimezone:
              type: string
              description: Client's timezone
              example: America/Chicago (UTC-05:00)
            countryTimezoneTime:
              type: string
              description: Client's current local time (HH:MM)
              example: '07:16'
            industry:
              type: string
              description: Client's industry
            companySize:
              type: string
              description: Client company size (number of employees)
            phoneVerified:
              type: boolean
              description: Whether the client's phone number is verified
            registeredAt:
              type: string
              format: date-time
              description: When the client registered on the marketplace
            jobsPosted:
              type: integer
              description: Total jobs the client has posted
            jobsActive:
              type: integer
              description: Client's active contracts
            jobsOpen:
              type: integer
              description: Jobs the client currently has open
            totalHoursPaid:
              type: number
              description: Total hours the client has paid for
            rankLevel:
              type: integer
              description: Vollna's client quality rank
            rankDowngradeReason:
              type: object
              description: >-
                Present when negative work-history feedback capped the rank.
                Counts of low reviews and the cap applied.
              properties:
                lowReviews:
                  type: integer
                scoredReviews:
                  type: integer
                recentLowReviews:
                  type: integer
                cappedAt:
                  type: integer
            workHistory:
              type: array
              items:
                type: object
              description: >-
                Legacy duplicate of the top-level clientWorkHistory with
                camelCase keys. Prefer clientWorkHistory.
        clientWorkHistory:
          type: array
          nullable: true
          description: Client's work history with previous freelancers
          items:
            type: object
            properties:
              job_info:
                type: object
                properties:
                  uid:
                    type: string
                    nullable: true
                    description: Job UID
                  title:
                    type: string
                    nullable: true
                    description: Job title
                  type:
                    type: string
                    nullable: true
                    description: Job type
                  url:
                    type: string
                    format: uri
                    nullable: true
                    description: >-
                      Link to the job posting on Upwork. Null for private
                      work-history entries.
              status:
                type: string
                nullable: true
                description: Job status (e.g., 'ACTIVE' for jobs in progress)
              start_date:
                type: string
                nullable: true
                description: Job start date
              end_date:
                type: string
                nullable: true
                description: Job end date
              total_hours:
                type: number
                format: float
                nullable: true
                description: Total hours worked
              total_charge:
                type: number
                format: float
                nullable: true
                description: Total amount charged
              contractor_name:
                type: string
                nullable: true
                description: Name of the freelancer who worked the job
              feedback:
                type: object
                description: >-
                  Feedback from client to freelancer. Omitted when the entry has
                  none.
                properties:
                  score:
                    type: number
                    format: float
                    nullable: true
                    description: Rating score
                  comment:
                    type: string
                    nullable: true
                    description: Feedback comment
              feedback_to_client:
                type: object
                description: >-
                  Feedback from freelancer to client. Omitted when the entry has
                  none.
                properties:
                  score:
                    type: number
                    format: float
                    nullable: true
                    description: Rating score
                  comment:
                    type: string
                    nullable: true
                    description: Feedback comment
              rate:
                type: object
                description: Rate information. Omitted when the entry has none.
                properties:
                  amount:
                    type: number
                    format: float
                    nullable: true
                    description: Rate amount
    ServiceError:
      type: object
      properties:
        error:
          type: string
          description: Short error title
          example: Validation failed
        message:
          type: string
          description: What went wrong and what to send instead, written for the user
        fields:
          type: object
          description: >-
            Per-field messages keyed by dot path, when several fields fail at
            once
          additionalProperties:
            type: string
  responses:
    Unauthorized:
      description: Missing or unknown API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: The team's subscription is not active
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The plan has no API access, or the token team may not do this. message
        says why
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceError'
    TooManyRequests:
      description: More than 30 requests a minute. See Rate Limiting
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiToken:
      type: apiKey
      name: X-API-TOKEN
      in: header
      description: API token for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.