Projects

The projects endpoint lets developers fetch the top-level container objects that group together user tests, responses, and related assets. When retrieving a project, you can access metadata such as the project name, description, and creation details, along with references to the studies it contains. This makes it possible to organize and filter resources programmatically without needing to drill into each test individually.

Note: The Ballpark API currently exposes only project-level metadata and references. Detailed configuration of contained studies must be fetched separately through their respective endpoints.

Projects vs usertests

Ballpark makes a distinction between projects and usertests. Projects are what you see in a list in your dashboard; here we store project-level settings like the name, collaborators, visibility and device settings. The GraphQL type is ProjectNode.

Usertests are where your usertest itself and its results are available. The GraphQL type is UserTestNode. Here you can find things like share links, results (UserTestResult), media, and custom params.

Projects and usertests have a 1:1 relationship.

1: Fetch all projects

This query will list all workspace projects the authenticated user has access to, similar to how your ballpark workspace dashboard works.

Take note that we're asking the server to return the usertest UUID here which we will use in the next query

(For information on pagination, see Pagination)

query listProjects {
  user {
    company {
      projects(first: 10, sortBy: LAST_RESULT_OLDEST_FIRST) {
        edges { 
          node {
            name
            userTestUUID
          }
        }
      }
    }
  }
}

2: Fetch one or more specific usertests

Here we're taking the userTestUUID we retrieved with the query above and using it to retrieve the UserTestNode.

query fetchTest {
  userTest(uuid: "ut_645c4faa-5c2d-49b1-85fa-823ffbbbfa17") {
    projectDetails {
      name
    }
    pk
    uuid
  }
}

If we have more than one UserTestNode to fetch we can do that in a single query:

fragment utDetails on UserTestNode {
  projectDetails {
    name
  }
  pk
  uuid
  shareUrl
  shareLinks {
    url
    type
    isExpired
    isDeactivated
  }
  resultsSortFilter
}

query fetchTests {
  ut_1: userTest(uuid: "ut_645c4faa-5c2d-49b1-85fa-823ffbbbfa17") {
    ...utDetails
  }
  ut_2: userTest(uuid: "ut_21fa281d-7f4e-4cd0-8c41-b97fb4f143ea") {
    ...utDetails
  }
}