List what has happened in one group

GET

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

Bearer token
Permissiongroup-challenge/read
Per organization

Lists what has happened in one group that one of your students is an active member of, newest first: the group created, confirmed, members added, files uploaded, steps submitted, the work sent. It is the log every member of the group can read; notes and details the organizers keep are not included.

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. What your account did for a student is actor.role: partner with yours: true, and the student in onBehalfOf.

A page at a time: limit is 20 by default and at most 100.

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`.

Query parameters

Name	Type	Description
`page`optional	number	Page number. Defaults to 1. Example `1`
`limit`optional	number	Items per page. Defaults to 20, max 100. Example `20`

Responses

200 OK

Success: message is "Activity fetched successfully.".

Body

successbooleanrequired
Always true on a success.
one oftrue
messagestringrequired
exampleActivity fetched successfully.
paginationobject · PaginationMetarequired
Where one page sits in the whole list.
4 fields of pagination
- pagenumberrequired
  The page returned, counting from 1.
  min1example1
- limitnumberrequired
  Items per page: the limit you sent, 20 if you sent none, and never more than 100.
  min1max100example20
- totalnumberrequired
  Items across every page.
  min0example57
- totalPagesnumberrequired
  Pages at this limit: total / limit, rounded up.
  min0example3
dataarray of GroupChallengeActivityResponserequired
9 fields of each item
- _idstringrequired
  The entry’s id.
  example6650a1b2c3d4e5f6a7b8c9f0
- atstringrequired
  When it happened (UTC).
  formatdate-timeexample2026-10-20T16:02:11.000Z
- eventstringrequired
  What happened. New values may be added; ignore one you do not know.
  one ofgroup_createdgroup_renamedmember_addedmember_removedgroup_finalizedgroup_deletedgroup_restoredstep_unlockedfile_uploadedfile_replacedfile_deletedfile_rejectedstep_submittedstep_reopenedfinal_submittedfinal_reverted
  examplestep_submitted
- actorobject · GroupChallengePersonResponserequired
  Who did it. Your account acting for a student is partner with yours: true.
  4 fields of actor
  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
- viastringrequired
  Where it was done: the panel, the app, an AI assistant (mcp), this API, or the system itself. New values may be added; ignore one you do not know.
  one ofpanelappmcpapisystem
  exampleapi
- onBehalfOfobject · GroupChallengePersonResponsenullablerequired
  Whom it was done for: the student a partner acted for, or the teacher an administrator acted for. null otherwise.
  4 fields of onBehalfOf
  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
- subjectobject · GroupChallengePersonResponsenullablerequired
  The student it was about (added or removed), or null.
  4 fields of subject
  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
- stepobject · GroupChallengeActivityStepResponsenullablerequired
  The step it was about, or null.
  2 fields of step
  _idstringrequired
  The step’s id.
  example6650a1b2c3d4e5f6a7b8c9ee
  orderobjectnullablerequired
  Its position when the entry was written.
  example1
- fileobject · GroupChallengeActivityFileResponsenullablerequired
  The file it was about, or null.
  2 fields of file
  _idstringrequired
  The file’s id.
  example6650a1b2c3d4e5f6a7b8c9ef
  nameobjectnullablerequired
  Its name, only when one of your students did what the entry records; otherwise null.
  exampleproposal.pdf

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": "Activity fetched successfully.",
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 57,
    "totalPages": 3
  },
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9f0",
      "at": "2026-10-20T16:02:11.000Z",
      "event": "step_submitted",
      "actor": {
        "role": "student",
        "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
        "name": "Ada Lovelace",
        "yours": true
      },
      "via": "api",
      "onBehalfOf": {
        "role": "student",
        "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
        "name": "Ada Lovelace",
        "yours": true
      },
      "subject": {
        "role": "student",
        "studentId": "6650a1b2c3d4e5f6a7b8c9d0",
        "name": "Ada Lovelace",
        "yours": true
      },
      "step": {
        "_id": "6650a1b2c3d4e5f6a7b8c9ee",
        "order": 1
      },
      "file": {
        "_id": "6650a1b2c3d4e5f6a7b8c9ef",
        "name": "proposal.pdf"
      }
    }
  ]
}

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.

Example request

# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/group/<groupId>/activity?page=1&limit=20' \
  -H "Authorization: Bearer $TOKEN"

const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret

const res = await fetch('https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/group/<groupId>/activity?page=1&limit=20', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data, body.pagination);

<?php
$token = getenv('TOKEN'); // a short-lived token you minted with your API key and secret

$ch = curl_init('https://api.main-team.org/v1/<organizationId>/group-challenge/<challengeId>/group/<groupId>/activity?page=1&limit=20');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($response, true);
if ($status >= 400) {
    $error = $body['error'];
    throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
print_r($body['data']);
print_r($body['pagination']);