Fetch one group, with its steps and files

GET

/v1/{organizationId}/group-challenge/{challengeId}/group/{groupId}

Bearer token
Permissiongroup-challenge/read
Per organization

Reads one group that one of your students is an active member of, with each step, its state and its files. Steps appear once the teacher has confirmed the group (finalized).

canSubmit on a step and canFinalSubmit on the group are the answers submitGroupChallengeStep and submitGroupChallengeWork would give right now, so read the group before you submit.

Only your own students are named. Every other person — the other members, the teacher, the organizers — is shown by role alone, with studentId and name set to null, and a file’s name only when one of your students uploaded it.

Parameters

Path parameters

Name	Type	Description
`organizationId`required	stringpattern `^[0-9a-f]{24}$`	The organization’s `_id`: 24 hexadecimal digits, as `listOrganizations` (`GET /v1/organization`) lists it. Example `64b7f0c2a1d3e4f5a6b7c8d9`
`challengeId`required	string	The group challenge’s `_id`, from `listGroupChallenges`.
`groupId`required	string	The group’s `_id`, from `listGroupChallengeGroups` or a student’s `group`.

Responses

200 OK

Success: message is "Group fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleGroup fetched successfully.
dataobject · GroupChallengeGroupResponserequired
A group one or more of your students are in, with its steps.
17 fields of data
- _idstringrequired
  The group’s id: the groupId of the group operations.
  example6650a1b2c3d4e5f6a7b8c9ed
- challengeIdstringrequired
  The challenge it belongs to.
  example6650a1b2c3d4e5f6a7b8c9eb
- shortCodestringrequired
  A six-character code for the group, unique in the organization.
  example7KQ2MX
- nameobjectnullablerequired
  The name the teacher gave it, or null.
  examplenull
- displayNamestringrequired
  name, or "Group" and the short code when it has none.
  exampleGroup 7KQ2MX
- statusstringrequired
  awaiting_payment and draft while the teacher prepares it; finalized once confirmed, with its steps open one by one; completed once its work has been sent. New values may be added.
  one ofawaiting_paymentdraftfinalizedcompleted
  examplefinalized
- gradeGroupobject · GroupChallengeGradeGroupRefResponserequired
  The grade group its members come from.
  2 fields of gradeGroup
  _idstringrequired
  The grade group’s id within the challenge.
  example6650a1b2c3d4e5f6a7b8c9ec
  labelstringrequired
  Its name.
  exampleGroup 7-8-9
- memberCountnumberrequired
  How many students are in it, yours and others.
  example3
- yourStudentsarray of GroupChallengeMemberResponserequired
  Your students in it. The other members are counted in memberCount and not listed.
  5 fields of each item
  studentIdstringrequired
  The student’s _id, as registerStudent returned it.
  example6650a1b2c3d4e5f6a7b8c9d0
  firstNamestringrequired
  Their first name when they joined the group.
  exampleAda
  lastNamestringrequired
  Their last name then.
  exampleLovelace
  gradeNameobjectnullablerequired
  Their grade’s name then.
  example8
  addedAtstringnullablerequired
  When the teacher added them.
  formatdate-timeexample2026-10-05T13:20:00.000Z
- stepCountnumberrequired
  How many steps the group works through.
  example3
- stepsSubmittednumberrequired
  How many of them are submitted.
  example1
- createdAtstringnullablerequired
  When the teacher created it.
  formatdate-timeexample2026-10-05T13:20:00.000Z
- finalizedAtstringnullablerequired
  When the teacher confirmed it, or null.
  formatdate-timeexample2026-10-12T08:15:00.000Z
- finalSubmittedAtstringnullablerequired
  When its work was sent, or null.
  formatdate-timeexamplenull
- finalSubmittedByobject · GroupChallengePersonResponsenullablerequired
  Who sent the group’s work, or null while it has not been sent.
  4 fields of finalSubmittedBy
  rolestringrequired
  student, teacher, administrator (the organizers), partner (an API account, acting for a student) or system. New values may be added.
  one ofstudentteacheradministratorpartnersystem
  examplestudent
  studentIdobjectnullablerequired
  The student’s _id, only when they are yours; otherwise null.
  example6650a1b2c3d4e5f6a7b8c9d0
  nameobjectnullablerequired
  Their name, only when they are yours; otherwise null.
  exampleAda Lovelace
  yoursbooleanrequired
  Whether this is one of your students, or your account acting for one.
  exampletrue
- canFinalSubmitbooleanrequired
  Whether submitGroupChallengeWork would send the work now: every step is submitted and the challenge is open.
  examplefalse
- stepsarray of GroupChallengeGroupStepResponserequired
  The steps, in order, once the teacher has confirmed the group; empty before that.
  10 fields of each item
  _idstringrequired
  The step’s id: the stepId submitGroupChallengeStep takes.
  example6650a1b2c3d4e5f6a7b8c9ee
  ordernumberrequired
  Its position, from 1.
  example1
  titlestringrequired
  Its title.
  exampleProject proposal
  statestringrequired
  locked until the step before it is submitted, open while the group works on it, submitted once it is sent. New values may be added.
  one oflockedopensubmitted
  examplesubmitted
  openedAtstringnullablerequired
  When it opened.
  formatdate-timeexample2026-10-12T08:15:00.000Z
  submittedAtstringnullablerequired
  When it was submitted, or null.
  formatdate-timeexample2026-10-20T16:02:11.000Z
  submittedByobject · GroupChallengePersonResponsenullablerequired
  Who submitted it, or null. partner with yours: true is your account, acting for one of your students.
  4 fields of submittedBy
  rolestringrequired
  student, teacher, administrator (the organizers), partner (an API account, acting for a student) or system. New values may be added.
  one ofstudentteacheradministratorpartnersystem
  examplestudent
  studentIdobjectnullablerequired
  The student’s _id, only when they are yours; otherwise null.
  example6650a1b2c3d4e5f6a7b8c9d0
  nameobjectnullablerequired
  Their name, only when they are yours; otherwise null.
  exampleAda Lovelace
  yoursbooleanrequired
  Whether this is one of your students, or your account acting for one.
  exampletrue
  reopenCountnumberrequired
  How many times the organizers reopened it after a submit.
  example0
  canSubmitbooleanrequired
  Whether submitGroupChallengeStep would submit it now: it is open, it has a file, and the challenge is open.
  examplefalse
  filesarray of GroupChallengeFileResponserequired
  Its files, uploading, uploaded or submitted.
  8 fields of each item
  _idstringrequired
  The file’s id.
  example6650a1b2c3d4e5f6a7b8c9ef
  statusstringrequired
  uploading while the upload runs, draft once uploaded, submitted once its step is submitted. New values may be added.
  one ofuploadingdraftsubmitted
  examplesubmitted
  nameobjectnullablerequired
  The file’s name, only when one of your students uploaded it; otherwise null.
  exampleproposal.pdf
  fileTypeobjectnullablerequired
  Its type, by extension.
  examplepdf
  sizeobjectnullablerequired
  Its size in bytes, once uploaded; null while uploading.
  example1048576
  uploadedByobject · GroupChallengePersonResponserequired
  Who uploaded it.
  4 fields of uploadedBy
  rolestringrequired
  student, teacher, administrator (the organizers), partner (an API account, acting for a student) or system. New values may be added.
  one ofstudentteacheradministratorpartnersystem
  examplestudent
  studentIdobjectnullablerequired
  The student’s _id, only when they are yours; otherwise null.
  example6650a1b2c3d4e5f6a7b8c9d0
  nameobjectnullablerequired
  Their name, only when they are yours; otherwise null.
  exampleAda Lovelace
  yoursbooleanrequired
  Whether this is one of your students, or your account acting for one.
  exampletrue
  completedAtstringnullablerequired
  When the upload finished.
  formatdate-timeexample2026-10-20T15:47:03.000Z
  submittedAtstringnullablerequired
  When its step was submitted with it.
  formatdate-timeexample2026-10-20T16:02:11.000Z

Headers

X-RateLimit-Limit integer: Requests your account may make to this operation per window (100).
X-RateLimit-Remaining integer: Requests left in the current window.
X-RateLimit-Reset integer: Seconds until the current window ends.

Example

{
  "success": true,
  "message": "Group fetched successfully.",
  "data": {
    "_id": "6650a1b2c3d4e5f6a7b8c9ed",
    "challengeId": "6650a1b2c3d4e5f6a7b8c9eb",
    "shortCode": "7KQ2MX",
    "name": null,
    "displayName": "Group 7KQ2MX",
    "status": "finalized",
    "gradeGroup": {
      "_id": "6650a1b2c3d4e5f6a7b8c9ec",
      "label": "Group 7-8-9"
    },
    "memberCount": 3,
    "yourStudents": [
      {
        "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "gradeName": "8",
        "addedAt": "2026-10-05T13:20:00.000Z"
      }
    ],
    "stepCount": 3,
    "stepsSubmitted": 1,
    "createdAt": "2026-10-05T13:20:00.000Z",
    "finalizedAt": "2026-10-12T08:15:00.000Z",
    "finalSubmittedAt": null,
    "finalSubmittedBy": {
      "role": "student",
      "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
      "name": "Ada Lovelace",
      "yours": true
    },
    "canFinalSubmit": false,
    "steps": [
      {
        "_id": "6650a1b2c3d4e5f6a7b8c9ee",
        "order": 1,
        "title": "Project proposal",
        "state": "submitted",
        "openedAt": "2026-10-12T08:15:00.000Z",
        "submittedAt": "2026-10-20T16:02:11.000Z",
        "submittedBy": {
          "role": "student",
          "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
          "name": "Ada Lovelace",
          "yours": true
        },
        "reopenCount": 0,
        "canSubmit": false,
        "files": [
          {
            "_id": "6650a1b2c3d4e5f6a7b8c9ef",
            "status": "submitted",
            "name": "proposal.pdf",
            "fileType": "pdf",
            "size": 1048576,
            "uploadedBy": {
              "role": "student",
              "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
              "name": "Ada Lovelace",
              "yours": true
            },
            "completedAt": "2026-10-20T15:47:03.000Z",
            "submittedAt": "2026-10-20T16:02:11.000Z"
          }
        ]
      }
    ]
  }
}

400 Bad request

bad_request: challengeId is not 24 hexadecimal digits.
bad_request: groupId is not 24 hexadecimal digits.

When

bad_request
challengeId is not 24 hexadecimal digits.
bad_request
groupId is not 24 hexadecimal digits.

Example

{
  "error": {
    "code": "bad_request",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "message": "Invalid value for 'challengeId': expected ObjectId.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

401 Unauthorized

unauthorized: The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

When

unauthorized
The token is missing or malformed, is not signed with your account’s apiSecret, breaks the iat and exp rules, has expired or been revoked, or its account is not active. All of these answer the same.

Example

{
  "error": {
    "code": "unauthorized",
    "documentation_url": "https://hub.main-team.org/api/errors#unauthorized",
    "message": "Authentication is required or the provided credentials are invalid.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

403 Forbidden

forbidden: The token is valid, but no role on your account allows group-challenge/read on the organization in the path, or a role denies it.

When

forbidden
The token is valid, but no role on your account allows group-challenge/read on the organization in the path, or a role denies it.

Example

{
  "error": {
    "code": "forbidden",
    "documentation_url": "https://hub.main-team.org/api/errors#forbidden",
    "message": "Insufficient role permissions",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

404 Not found

not_found: organizationId is not the _id of an organization.
not_found: Group challenges are not switched on for this organization. The answer is the one an unknown path gets; nothing was read.
not_found: No group challenge of this organization has this id, or it is not published: a draft, archived or deleted challenge answers the same.
not_found: No group of this challenge has this id that one of your students is an active member of: a missing group, a deleted one and another account’s get the same answer.

When

not_found
organizationId is not the _id of an organization.
not_found
Group challenges are not switched on for this organization. The answer is the one an unknown path gets; nothing was read.
not_found
No group challenge of this organization has this id, or it is not published: a draft, archived or deleted challenge answers the same.
not_found
No group of this challenge has this id that one of your students is an active member of: a missing group, a deleted one and another account’s get the same answer.

Example

{
  "error": {
    "code": "not_found",
    "documentation_url": "https://hub.main-team.org/api/errors#not_found",
    "message": "Organization not found!",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

429 Too many requests

too_many_requests: Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

When

too_many_requests
Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in Retry-After before sending again.

Headers

Retry-After integer: Seconds to wait before sending again; a request sent sooner is refused too.

Example

{
  "error": {
    "code": "too_many_requests",
    "documentation_url": "https://hub.main-team.org/api/errors#too_many_requests",
    "message": "Too many requests to this operation. Wait the number of seconds in Retry-After, then try again.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

500 Internal error

internal_error: Something failed on our side. Retry later, and quote request_id if it goes on.

When

internal_error
Something failed on our side. Retry later, and quote request_id if it goes on.

Example

{
  "error": {
    "code": "internal_error",
    "documentation_url": "https://hub.main-team.org/api/errors#internal_error",
    "message": "An unexpected error occurred.",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

Fields of the error body

errorobject · ErrorDetailrequired
What went wrong.
5 fields of error
- codestringrequired
  A stable machine code: branch on this. Each one is explained at documentation_url.
  one ofinvalid_emailbad_requestunauthorizedforbiddennot_foundconflictpayload_too_largeunsupported_media_typeunprocessable_entitytoo_many_requestsinternal_errorservice_unavailable
  examplenot_found
- messagestringrequired
  Written for a person, and may change: never branch on it.
  exampleNot found!
- documentation_urlstringrequired
  Where this code is explained.
  formaturiexamplehttps://hub.main-team.org/api/errors#not_found
- request_idstringrequired
  This request’s id, also sent as the X-Request-Id response header: the one you sent, when it was acceptable, or else one the API made. Quote it when you report a problem.
  example0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e
- detailsobject
  Present only where an operation says so, and then with the shape that operation documents — the rows it could not accept, say. Treat it as absent everywhere else, and ignore a details you do not recognise.

Fetch one group, with its steps and files

Parameters

Path parameters

Responses

Example request

Try it